Daftar Isi

1. Ringkasan Eksekutif

Sistem Keuangan Santri Latee adalah sistem informasi manajemen keuangan santri untuk Pondok Pesantren Annuqayah, dibangun sebagai aplikasi web (Laravel 13 + Livewire 4) dengan aplikasi pendamping mobile (Flutter) khusus untuk wali santri. Sistem ini menggantikan proses pencatatan tagihan, pembayaran, top up saldo, dan penarikan tunai yang sebelumnya dilakukan secara manual/tunai penuh, dengan model dompet digital (saldo) per santri yang tercatat dalam buku besar (ledger) yang tidak dapat diubah, terintegrasi dengan payment gateway Midtrans untuk pembayaran non-tunai, serta kios swalayan (self-service) berbasis kartu RFID dan sidik jari untuk penarikan tunai tanpa perlu antre ke petugas.

Dokumen ini disusun secara retroaktif - sistem yang dideskripsikan di sini sudah dibangun dan berjalan, bukan rencana ke depan. Tujuannya adalah menyediakan dokumentasi kebutuhan produk yang lengkap dan terstruktur sebagai baseline resmi sebelum pengembangan/penyempurnaan lanjutan dilakukan, sehingga setiap perubahan berikutnya punya rujukan yang jelas tentang apa yang sudah ada, mengapa dibangun demikian, dan batasan yang berlaku.

Sistem melayani 6 peran pengguna (admin, bendahara, pengasuh, wali, santri, dan developer/dev-only) melalui portal web yang berbeda sesuai peran, ditambah aplikasi mobile khusus wali. Fitur inti mencakup manajemen data santri & keluarga, kartu santri digital (RFID), tagihan otomatis dengan dukungan cicilan dan diskon, top up saldo & pembayaran tagihan via Midtrans, penarikan tunai (baik lewat admin maupun swalayan di kios), manajemen perangkat kios, serta laporan keuangan.

2. Latar Belakang & Rumusan Masalah

Sebelum sistem ini dibangun, pengelolaan keuangan santri di pesantren pada umumnya menghadapi beberapa masalah klasik yang menjadi latar belakang pembangunan sistem ini:

• Uang tunai fisik di tangan santri - risiko kehilangan/pencurian, sulit dipantau orang tua, dan menyulitkan pengurus dalam rekonsiliasi.
• Pencatatan tagihan & pembayaran manual - rawan human error, sulit diaudit, dan menyulitkan orang tua/wali memantau tunggakan dari jarak jauh.
• Tidak ada mekanisme pembayaran non-tunai yang terintegrasi - wali harus datang langsung atau transfer manual yang perlu dicocokkan satu per satu oleh bendahara.
• Penarikan tunai santri bergantung sepenuhnya pada petugas - antrean panjang di jam-jam sibuk, dan tidak ada jejak audit lokasi/waktu transaksi yang konsisten.
• Minimnya transparansi bagi wali - wali tidak punya cara mudah untuk melihat riwayat transaksi, sisa tagihan, atau saldo anaknya secara real-time.

Rumusan masalah yang dijawab oleh sistem ini: bagaimana pesantren dapat mengelola dana santri secara digital, aman, transparan bagi wali, dan efisien secara operasional bagi petugas - tanpa menghilangkan kontrol dan jejak audit yang dibutuhkan sebuah institusi keuangan?

3. Tujuan & Sasaran

3.1 Tujuan Utama

• Menggantikan pengelolaan uang tunai fisik santri dengan saldo digital yang tercatat, dapat diaudit, dan aman.
• Menyediakan kanal pembayaran tagihan & top up non-tunai (Midtrans) bagi wali, tanpa mengharuskan kehadiran fisik ke pesantren.
• Memberi wali visibilitas penuh atas saldo, tagihan, dan riwayat transaksi anaknya - baik lewat web maupun aplikasi mobile.
• Mempercepat proses penarikan tunai santri lewat kios swalayan berbasis kartu + sidik jari, tanpa mengorbankan kontrol untuk kasus yang butuh persetujuan (nominal besar/di luar kebijakan).
• Menjaga integritas keuangan lewat buku besar (ledger) yang tidak dapat diubah/dihapus, sehingga setiap pergerakan saldo selalu bisa ditelusuri.

3.2 Sasaran Terukur

• Seluruh transaksi keuangan (topup, pembayaran tagihan, penarikan) tercatat otomatis tanpa input manual ganda.
• Wali dapat menyelesaikan pembayaran tagihan atau top up dalam kurang dari 3 langkah dari aplikasi mobile.
• Penarikan tunai dalam kebijakan (saldo cukup, jam operasional, dalam limit harian) dapat diselesaikan santri sendiri di kios tanpa antre ke petugas.
• Setiap perangkat kios fisik dapat diidentifikasi lokasinya untuk keperluan audit transaksi penarikan.

4. Ruang Lingkup

4.1 Dalam Lingkup (Sudah Dibangun)

• Portal web admin/bendahara/pengasuh/wali/santri (Laravel + Livewire), termasuk manajemen data master, tagihan, transaksi, laporan, dan pengaturan sistem.
• Aplikasi mobile wali (Flutter, Android & iOS) sebagai pendamping portal web wali.
• Integrasi payment gateway Midtrans (Snap & Core API) untuk top up saldo dan pembayaran tagihan langsung.
• Kios swalayan publik (tanpa login) untuk cek saldo dan penarikan tunai mandiri berbasis kartu RFID + sidik jari.
• Manajemen perangkat/kios fisik beserta status aktif/nonaktif dan petugas jaga.
• Backup & restore basis data dari dalam aplikasi.
• Unit Usaha (Kantin/Koperasi) - wali membayar lewat aplikasi mobile dengan memindai kode QR unit usaha, ledger saldo unit usaha terpisah dari saldo santri, serta pengelolaan/pencairan/perubahan rekening oleh akun pengelola. Lihat 7.9.
• Transfer saldo antar santri bersaudara - wali dapat memindahkan saldo langsung antar anaknya yang terdaftar di Kartu Keluarga yang sama, dari aplikasi mobile.
• PIN transaksi - lapisan verifikasi tambahan (terpisah dari kata sandi akun) yang menggerbangi setiap aksi pemindahan saldo dari aplikasi mobile (bayar tagihan dari saldo, bayar kantin, transfer antar santri).
• Notifikasi push (Firebase Cloud Messaging) - pemberitahuan otomatis ke aplikasi mobile wali untuk tagihan baru dan pengingat jatuh tempo.
• Banner beranda - carousel pengumuman/promosi (mis. ajakan donasi/hibah wali) di layar Home aplikasi mobile, dikelola admin.
• Kwitansi resmi bernomor - diterbitkan otomatis untuk setiap pembayaran tagihan dan pembayaran kantin, menggantikan struk informal untuk kedua jenis transaksi tersebut. Lihat 7.11.
• Kebijakan Belanja Kantin - batas nominal belanja kantin harian per santri, admin-configurable, mirip Kebijakan Penarikan tapi untuk pembayaran kantin. Lihat 7.9.

4.2 Di Luar Lingkup (Belum Dibangun / Sengaja Ditunda)

• Kios fisik untuk kantin - tersedia melalui URL khusus perangkat /kios-kantin/{kode_device}. Petugas memasukkan nominal, lalu santri mengotorisasi dengan kartu RFID dan sidik jari; transaksi langsung mendebit saldo santri dan mengkredit saldo unit usaha secara atomik.
• Pendaftaran wali mandiri (self-registration) - akun wali hanya dapat dibuat oleh admin/pengurus (`WaliAccountService`), wali tidak bisa mendaftar sendiri lewat aplikasi.
• Pembayaran cicilan via Midtrans - fitur cicilan (pembayaran sebagian) saat ini hanya berlaku untuk pembayaran dari saldo; opsi Midtrans (baik Snap di web maupun Core API di mobile) selalu menagih nominal penuh sisa tagihan.
• Alur Midtrans Snap di aplikasi mobile - mobile hanya menggunakan Core API (VA/QRIS) karena tidak memiliki WebView; Snap (redirect ke halaman pembayaran Midtrans) hanya tersedia di portal web.
• Kwitansi resmi - kwitansi bernomor permanen diterbitkan untuk pembayaran tagihan, transaksi kantin, dan top up saldo via Midtrans. Penyesuaian internal serta transfer antar-santri tetap memakai bukti transaksi ledger karena bukan penerimaan pembayaran dari pihak luar.

5. Pengguna & Peran

Sistem menerapkan kontrol akses berbasis peran (role-based access control) menggunakan paket spatie/laravel-permission, dengan 6 peran berikut:

Catatan: kios (/kios/{kode_device}) tidak memerlukan login sama sekali - identitas santri diverifikasi lewat kartu RFID + sidik jari secara langsung di lokasi, bukan lewat akun pengguna.

6. Arsitektur Sistem

6.1 Komponen Utama

6.2 Prinsip Arsitektur Kunci

• Buku besar (ledger) sebagai satu-satunya sumber kebenaran saldo - setiap perubahan saldo (`SaldoSantri.saldo`) wajib melalui `WalletService::credit()`/`debit()`, yang selalu menghasilkan satu baris `Transaksi` yang tidak dapat diubah/dihapus (`ImmutableLedgerException` pada percobaan update/delete).
• Top up tidak lagi otomatis memotong tagihan - setiap top up selalu 100% masuk ke saldo; pembayaran tagihan adalah keputusan eksplisit terpisah (dari saldo, atau Midtrans langsung untuk tagihan tersebut).
• Kios web berbasis URL per-perangkat - setiap mesin kios fisik punya URL sendiri (`/kios/{kode_device}`), sehingga transaksi penarikan otomatis dapat dikaitkan ke lokasi mesin tanpa memerlukan token API tersembunyi di URL.
• Web dan mobile berbagi backend & API yang sama - tidak ada logika bisnis yang diduplikasi; API `/api/wali/*` memanggil service yang sama (`TagihanService`, `WalletService`, `TopupWaliService`) yang juga dipakai portal web wali.

7. Kebutuhan Fungsional (Aplikasi Web)

7.1 Manajemen Data Santri & Keluarga Selesai

• Data Santri (`/admin/santri`) - CRUD lengkap, verifikasi santri baru (status `baru` → `aktif`), impor massal dari Excel/CSV dengan opsi pembuatan akun wali sekaligus, ekspor Excel/PDF, dan hapus santri yang diblokir selama saldo lebih dari 0 (harus ditarik/dipindahkan dulu).
• Data Keluarga (`/admin/keluarga`) - CRUD keluarga, deteksi No. KK duplikat, pembuatan akun wali (satu per satu atau massal) yang otomatis dikaitkan ke keluarga terkait; kredensial wali baru dapat diunduh sebagai PDF.
• Data Wali Santri (`/admin/wali`) - menautkan/melepas akun wali yang sudah ada ke santri tertentu (mendukung wali dengan banyak anak).
• Kartu Santri (RFID) (`/admin/kartu`) - aktivasi kartu (kaitkan UID fisik ke santri), otomatis menonaktifkan kartu lama saat penerbitan ulang, cetak kartu satuan/massal ke PDF.

7.2 Tagihan & Pembayaran Selesai

• Jenis Tagihan (`/admin/tagihan/jenis`) - master jenis tagihan (SPP, uang pangkal, dsb.) dengan nominal default, periode (bulanan/tahunan/sekali), keterkaitan lembaga, status berlaku diskon, dan flag "boleh dicicil" yang mengizinkan pembayaran sebagian.
• Kategori Diskon (`/admin/kategori-diskon`) - kategori diskon per santri, termasuk auto-assign diskon saudara kandung (`BERSAUDARA`) dan santri baru (`SANTRI_BARU`).
• Periode (`/admin/periode`) - master periode tagihan, dengan auto-expire periode lama.
• Generate Tagihan (`/admin/tagihan/generate`) - pembuatan tagihan massal dengan 3 mode target: seluruh santri aktif, berdasarkan lembaga tertentu, atau pilih santri secara manual. Idempoten (menjalankan ulang untuk jenis+periode yang sama tidak membuat duplikat).
• Daftar & Pembayaran Tagihan (`/admin/tagihan`) - pencarian/filter status/periode, pencatatan pembayaran tunai langsung oleh admin, dan badge sumber pembayaran (Tunai Langsung / Saldo / Transfer Wali Otomatis / Transfer Wali Bayar Langsung) untuk setiap tagihan yang sudah lunas - termasuk menampilkan gabungan beberapa sumber bila tagihan dicicil lewat lebih dari satu metode.
• Pembayaran cicilan (installment) - untuk jenis tagihan yang mengizinkan, wali dapat membayar sebagian dari saldo (nominal custom, divalidasi ≤ sisa tagihan); status tagihan otomatis menjadi "Sebagian" hingga lunas. Riwayat transaksi menampilkan progres terbayar/sisa untuk cicilan yang masih berjalan.

7.3 Saldo & Dompet Digital Selesai

• Setiap santri memiliki satu saldo digital (`SaldoSantri`) yang hanya dapat berubah lewat `WalletService`, dengan kunci baris basis data (row locking) untuk mencegah kondisi balapan (race condition) pada transaksi bersamaan.
• Batas saldo minimum (saldo floor) yang dapat dikonfigurasi admin (`Pengaturan Midtrans`, default Rp 100.000) - melindungi santri agar pembayaran tagihan dari saldo tidak menguras saldo sampai di bawah batas aman; wali diberi tahu "saldo bisa digunakan" secara eksplisit di web maupun mobile, terpisah dari saldo mentah.
• Riwayat transaksi (`/admin/transaksi`, portal wali & santri) menampilkan buku besar lengkap - topup, pembayaran tagihan, penarikan, penyesuaian - dengan jejak saldo sebelum/sesudah pada setiap baris.

7.4 Top Up & Integrasi Midtrans Selesai

• Wali dapat top up saldo santri kapan saja lewat Midtrans (Snap di web, Core API/VA-QRIS di mobile) - 100% nominal selalu masuk ke saldo, tidak ada potongan otomatis untuk tagihan.
• Pembayaran tagihan langsung via Midtrans ("Bayar Langsung") tersedia sebagai opsi terpisah dari top up - membayar tepat nominal sisa tagihan tanpa menyentuh saldo sama sekali.
• Audit terpisah untuk dua jenis transaksi Midtrans (`/admin/topup`) - badge & filter yang membedakan "Top Up Saldo" dari "Bayar Tagihan Langsung", karena keduanya secara arsitektur berbeda (yang kedua tidak pernah tercatat di buku besar/`Transaksi` karena tidak menyentuh saldo).
• Sinkronisasi status manual (`Sync dari Midtrans`) untuk kasus webhook yang terlambat/gagal.

7.5 Penarikan Tunai Selesai

• Jalur admin (formal) (`/admin/penarikan`) - santri/wali mengajukan lewat portal, mengunggah surat keterangan bila di luar kebijakan (jam operasional/limit harian), admin mereview surat dan menyetujui, lalu petugas mencairkan dengan verifikasi sidik jari.
• Jalur kios swalayan (mandiri) (`/kios/{kode_device}`) - santri menempelkan kartu RFID, memasukkan nominal (jika sesuai kebijakan: saldo cukup, dalam jam operasional, dalam limit harian), verifikasi sidik jari langsung di kios, dan uang tunai keluar tanpa perlu persetujuan petugas sama sekali. Nominal di luar kebijakan otomatis diarahkan ke jalur formal.
• Kebijakan Penarikan (`/admin/kebijakan-penarikan`) - jam operasional, limit harian, dapat dibatasi per lembaga.

7.6 Manajemen Perangkat Kios Selesai

• Pendaftaran setiap mesin kios fisik (`/admin/perangkat`) - kode unik (menjadi bagian URL kios), nama, lokasi, tipe (kiosk cek saldo / kiosk penarikan / kantin), status aktif/nonaktif.
• Panduan setup bawaan di aplikasi - langkah pemasangan RFID reader, terminal sidik jari, dan mode kios browser untuk tiap perangkat, tanpa perlu dokumentasi eksternal.
• Petugas jaga - staf dapat "mengklaim" diri sebagai penanggung jawab suatu mesin untuk memudahkan koordinasi bila ada gangguan, dengan status "terakhir aktif" yang dihitung otomatis dari aktivitas pemindaian kartu terakhir.
• Status aktif/nonaktif benar-benar menentukan apakah mesin dapat melayani penarikan mandiri - bukan sekadar label.

7.7 Laporan Keuangan Selesai

• Laporan Keuangan (`/admin/laporan-keuangan`) - ringkasan keuangan per rentang tanggal & lembaga, ekspor Excel/PDF.
• Leger Kas Pondok (`/admin/leger-kas-pondok`) - buku kas pondok dengan filter sumber dana, ekspor Excel.
• Laporan Santri (portal pengasuh) - saldo & jumlah tunggakan per santri, dapat dicari dan diekspor.
• Invoice/kwitansi - setiap transaksi, top up, penarikan, dan tagihan dapat dicetak sebagai PDF individual.

7.8 Manajemen Pengguna & Pengaturan Sistem Selesai

• Pengguna (`/admin/users`) - CRUD akun lintas peran.
• Lembaga (`/admin/lembaga`) - data induk unit/lembaga di bawah pondok.
• Pengaturan Aplikasi - nama aplikasi/pondok, alamat, kontak (memengaruhi branding di seluruh sistem, termasuk halaman error & invoice).
• Pengaturan Midtrans - kredensial server/client key, mode sandbox/produksi, dan batas saldo minimum.
• Backup & Restore (`/admin/backup`, khusus admin) - buat/unduh/hapus/pulihkan backup basis data, pemulihan memerlukan kode konfirmasi yang diketik manual sebagai pengaman tambahan.

7.9 Unit Usaha (Kantin/Koperasi) Selesai

• Kelola Kantin (`/admin/kantin`, khusus admin) - CRUD unit usaha (kode unik yang di-encode ke kode QR, rekening bank tujuan pencairan), pembuatan akun pengelola (satu akun mengelola paling banyak satu unit usaha).
• Pembayaran dari wali - wali memindai kode QR unit usaha lewat aplikasi mobile (menu Scan QR), memasukkan nominal, verifikasi PIN transaksi - saldo santri didebit dan saldo unit usaha dikredit secara atomik (`KantinPembayaranService`). Tidak melibatkan kios/perangkat fisik apa pun - murni HP wali + kode QR cetak di kantin.
• Ledger terpisah (`unit_usaha_transaksis`) - saldo unit usaha adalah pendapatan unit usaha itu sendiri, sengaja dipisah dari `saldo_santris`/`transaksis` karena unit usaha bukan santri.
• Penarikan Kantin (`/admin/kantin/penarikan`) - pengelola mengajukan pencairan saldo unit usaha ke rekening terdaftar, disetujui & dicairkan admin/bendahara.
• Perubahan Rekening (`/admin/kantin/rekening`) - pengajuan ganti rekening bank tujuan pencairan oleh pengelola, tidak langsung berlaku sampai disetujui admin/bendahara (mencegah pengalihan sepihak).
• Riwayat Transaksi Kantin (`/admin/kantin/ledger`) - buku besar unit usaha, dapat difilter, dengan tautan cetak ulang kwitansi per baris pembayaran masuk.
• Kebijakan Belanja Kantin (`/admin/kantin/kebijakan`) - batas nominal belanja kantin harian per santri (opsional per lembaga), diperiksa `KantinPembayaranService` sebelum saldo didebit - lihat 7.9.1.

7.9.1 Kebijakan Belanja Kantin (Batas Harian) Selesai

Sama seperti Kebijakan Penarikan (7.5) melindungi berapa banyak uang tunai yang bisa ditarik santri per hari, Kebijakan Belanja Kantin melindungi berapa banyak yang bisa dibelanjakan santri di kantin per hari - keduanya menjawab kekhawatiran wali yang sama: "uang jajan" semestinya punya batas harian, terlepas dari berapa total saldo yang tersedia (yang sebagian mungkin dititipkan untuk SPP, bukan untuk jajan).

• Terpisah dari batas minimum saldo (SaldoFloorService) - keduanya bisa aktif bersamaan, keduanya diperiksa sebelum saldo didebit.
• Opsional: tanpa kebijakan aktif, belanja kantin tidak dibatasi secara harian (perilaku sebelum fitur ini ada).
• Dihitung dari total pembayaran_kantin berstatus berhasil milik santri pada hari berjalan (`whereDate('created_at', today())`), bukan jendela bergulir 24 jam.
• Melempar LimitKantinHarianException (kode limit_kantin_harian) jika pembayaran akan melebihi limit - pesan errornya menyebutkan nominal limit dan berapa yang sudah terpakai hari itu, ditampilkan apa adanya di aplikasi mobile.

7.10 Banner Beranda Selesai

• Banner Beranda (`/admin/banner`, khusus admin) - CRUD banner pengumuman/promosi (mis. ajakan donasi/hibah wali ke pesantren) untuk carousel di layar Home aplikasi mobile: unggah gambar, tautan opsional (dibuka saat banner disentuh), status aktif/nonaktif, dan urutan tampil.
• Aturan tampilan di mobile - tidak ada banner aktif: bagian ini tersembunyi sepenuhnya (tidak ada spasi kosong tersisa); tepat satu banner aktif: tampil penuh lebar; dua atau lebih: carousel dengan banner berikutnya sedikit terlihat di tepi kanan + indikator titik.
• Diekspos lewat endpoint publik GET /api/wali/banners (tanpa token, sama seperti info aplikasi) - hanya mengembalikan banner berstatus aktif, terurut sesuai kolom urutan.

7.11 Kwitansi Resmi Selesai

Menggantikan struk informal (`InvoiceService`, nomor referensi diturunkan ulang dari id record setiap kali dicetak, tidak pernah disimpan) untuk dua jenis transaksi yang paling sering butuh bukti formal: pembayaran tagihan dan pembayaran kantin.

• Diterbitkan otomatis saat pembayaran berhasil - `TagihanService::applyPembayaran()` (mencakup ketiga sumber pembayaran tagihan: saldo, tunai langsung, transfer wali langsung) dan `KantinPembayaranService::bayar()` sama-sama memanggil `KwitansiService`, jadi satu-satunya kode yang pernah menerbitkan kwitansi resmi.
• Nomor permanen (format KWT-{tahun}-{6 digit}, mis. KWT-2026-000123) - diberikan tepat sekali saat diterbitkan berdasarkan id baris `kwitansis` sendiri (aman dari duplikat di bawah pembayaran bersamaan, karena mengandalkan jaminan auto-increment database, bukan hitungan MAX+1 sebelum insert), dan tidak pernah berubah walau dokumennya dicetak ulang berkali-kali.
• Akses wali (mobile) - tombol "Unduh Kwitansi Resmi (PDF)" di layar Detail Transaksi, memakai tautan bertanda tangan (`URL::temporarySignedRoute`, berlaku 15 menit) yang diminta lewat GET /api/wali/kwitansi/{id} lalu dibuka langsung via browser eksternal - tidak perlu mengunduh byte PDF lewat token Bearer.
• Akses admin (web) - tautan cetak ulang di halaman Tagihan (per baris pembayaran) dan Riwayat Transaksi Kantin, mencatat staf & waktu cetak ulang (`dicetak_oleh`/`dicetak_at`) - berbeda dari penerbitan otomatis, yang tidak pernah mengisi kedua kolom ini.
• Dokumen sama, judul beda - menggunakan template PDF `pdf.invoice` yang sama dengan struk informal, dengan judul "KWITANSI RESMI" dan catatan kaki yang menyebutkan nomornya permanen, alih-alih membangun template terpisah.

8. Aplikasi Mobile Wali

Aplikasi Flutter (nama paket wali_santri, target Android & iOS) yang menjadi pendamping portal web khusus wali, mengonsumsi API yang sama (`/api/wali/*`). Berikut kebutuhan fungsional yang sudah diimplementasikan:

8.1 Fitur Inti

• Login & Sesi - login dengan email/No. KK + kata sandi, token disimpan aman di perangkat (`flutter_secure_storage`), sesi dipulihkan otomatis saat aplikasi dibuka kembali.
• Beranda - kartu saldo (lebar penuh), 5 aksi cepat (Transfer/Top Up/Riwayat/Scan QR/Profil), ringkasan tagihan aktif & total tunggakan (dapat disentuh langsung ke Tagihan dengan filter yang sesuai), pratinjau tagihan & aktivitas terbaru, carousel banner pengumuman (lihat 7.10), dengan dukungan ganti-santri bila wali punya lebih dari satu anak.
• Tagihan - daftar tagihan dengan filter status, detail rincian (termasuk diskon), bayar dari saldo (termasuk cicilan bila diizinkan, dengan rincian & dialog konfirmasi sebelum eksekusi) atau bayar langsung via Midtrans (VA/QRIS), cetak struk pembayaran. Mendukung pembayaran beberapa tagihan sekaligus (mode pilih banyak) - satu kali verifikasi PIN, diproses berurutan per tagihan, tiap pembayaran tetap tercatat sebagai baris terpisah (bukan digabung), dengan ringkasan hasil per tagihan di akhir.
• Riwayat Transaksi - riwayat lengkap dengan filter jenis, dikelompokkan per tanggal relatif (Hari Ini/Kemarin/tanggal), termasuk catatan progres cicilan pada baris pembayaran tagihan yang masih berjalan. Detail transaksi pembayaran tagihan (dari saldo) dan kantin menampilkan tombol "Unduh Kwitansi Resmi (PDF)" (lihat 7.11).
• Top Up Saldo - top up via Midtrans Core API (VA BNI/BCA/BRI atau QRIS), ditampilkan langsung di aplikasi (nomor VA/kode QR) tanpa perlu membuka browser.
• Transfer Saldo - wali memindahkan saldo langsung antar anaknya yang satu Kartu Keluarga, dengan verifikasi PIN transaksi (lihat 4.1).
• Scan QR Bayar Kantin - memindai kode QR unit usaha (viewfinder bergaya bracket sudut) untuk membayar langsung dari saldo, verifikasi PIN transaksi, tunduk pada batas belanja harian bila kebijakannya aktif (lihat 7.9/7.9.1) - pesan error menyebutkan nominal limit & yang sudah terpakai bila melebihi.
• PIN Transaksi - pengaturan PIN 6 digit (memerlukan verifikasi kata sandi akun lebih dulu) yang kemudian menggerbangi bayar tagihan dari saldo, bayar kantin, dan transfer antar santri.
• Profil Santri - kartu identitas informatif per anak (foto, NIS, lembaga/kelas, status, biodata) - murni tampilan, tidak menyertakan data kredensial kartu RFID fisik (`KartuSantri.uid_kartu` tetap terenkripsi & tidak pernah diekspos ke API mobile).
• Notifikasi Push - pemberitahuan Firebase Cloud Messaging untuk tagihan baru & pengingat jatuh tempo, dikirim ke seluruh perangkat wali yang terhubung ke santri bersangkutan; gagal kirim tidak pernah menggagalkan aksi keuangan yang memicunya (fire-and-forget).
• Profil (Akun) - ubah profil, ganti kata sandi, dan pengaturan login sidik jari.

8.2 Keamanan Sesi

• Login sidik jari (opsional) - wali dapat mengaktifkan pembukaan aplikasi lewat sidik jari/Face ID bawaan HP sebagai pengganti mengetik kata sandi setiap kali. Sidik jari berfungsi sebagai kunci lokal di depan sesi yang sudah tersimpan - tidak pernah dikirim atau diverifikasi ke server. Otomatis disembunyikan pada perangkat tanpa sensor/pendaftaran sidik jari. Tersedia juga opsi "gunakan akun lain" dari layar kunci sidik jari, memaksa keluar penuh (bukan soft-lock) dan mencabut persetujuan sidik jari akun sebelumnya.
• Penguncian sesi saat aplikasi diminimalkan - sesi langsung terkunci begitu aplikasi berpindah ke latar belakang (tanpa jeda/masa tenggang), bukan hanya setelah beberapa menit - aplikasi finansial ini sengaja tidak memberi celah "sempat keluar sebentar tanpa verifikasi ulang". Bila login sidik jari aktif, ini berupa soft-lock (cukup verifikasi sidik jari untuk lanjut, sesi tetap valid); bila tidak, wali di-logout penuh dan harus login ulang.
• Auto-logout karena tidak aktif di latar depan - terpisah dari poin di atas: bila aplikasi dibiarkan diam (tanpa disentuh, tetap di layar) selama 5 menit, sesi otomatis terkunci dengan pola yang sama (soft-lock jika sidik jari aktif, logout penuh jika tidak).

8.3 Pembaruan Antarmuka (Redesign)

Tampilan aplikasi mobile disegarkan mengikuti karakteristik brand yang sudah ada (teal `#0F766E`, latar abu muda `#F7F8FA`), mengadopsi pola tata letak dari referensi aplikasi fintech modern tanpa mengambil alih palet warnanya:

• Layar kunci sidik jari - lingkaran sentuh lebih besar, sapaan bernama dengan aksen tipografi serif miring.
• Riwayat transaksi & pratinjau di beranda - daftar rata (tanpa kartu berbingkai), dipisah garis tipis, dikelompokkan per tanggal relatif.
• Viewfinder Scan QR - bingkai sudut (bracket) dengan animasi garis pindai, bukan kotak bergaris polos.
• Beranda - kartu saldo lebar penuh, 5 aksi cepat rata kiri-kanan mengikuti lebar kartu di atasnya, ringkasan tagihan sebagai chip berwarna (bukan satu strip putih polos), carousel banner.
• Tagihan - kartu lebih rapi, mode pilih-banyak untuk pembayaran sekaligus.

8.4 Keterbatasan yang Diketahui pada Mobile

• Pembayaran Midtrans di mobile hanya mendukung Core API (VA/QRIS) - tidak ada Snap, karena aplikasi tidak memiliki komponen WebView untuk menampilkan halaman checkout Midtrans.
• Kwitansi resmi bernomor (7.11) hanya untuk pembayaran tagihan dan kantin - top up dan transaksi lain masih memakai struk informal (`InvoiceService`) tanpa nomor permanen.
• Pembayaran tagihan sekaligus (multi-pilih) hanya mendukung sumber saldo - opsi Midtrans per tagihan tetap harus dilakukan satu per satu, di luar mode pilih-banyak.
• Kwitansi resmi untuk pembayaran tagihan via transfer_wali_tagihan (Midtrans langsung, tidak menyentuh saldo) diterbitkan & bisa dicetak ulang dari admin, tapi belum ada tombol unduh langsung di layar mobile manapun (alur Midtrans-langsung ini tidak menghasilkan baris `Transaksi`, sehingga tidak muncul di Riwayat Transaksi seperti kwitansi kantin/saldo).

9. Kebutuhan Non-Fungsional

10. Model Data

Entitas utama dalam sistem (nama model Laravel):

11. Alur Pengguna Utama

11.1 Wali Membayar Tagihan (Cicilan, dari Saldo)

1. Wali membuka daftar tagihan anaknya (web/mobile), memilih tagihan yang berstatus belum lunas/sebagian.
2. Jika jenis tagihan mengizinkan cicilan, wali dapat memasukkan nominal kurang dari sisa tagihan (divalidasi antara Rp 1 s.d. sisa tagihan).
3. Sistem menampilkan rincian: nominal yang akan dibayar, sisa tagihan setelahnya, saldo santri setelah dibayar - wali mengonfirmasi secara eksplisit.
4. Sistem memvalidasi saldo mencukupi dan tidak akan membuat saldo turun di bawah batas minimum; jika lolos, saldo didebit dan tagihan diperbarui (`sebagian` atau `lunas` tergantung apakah sudah menutup penuh).
5. Transaksi tercatat di buku besar, dan riwayat transaksi menampilkan progres terbayar/sisa selama tagihan masih berstatus sebagian.

11.2 Santri Melakukan Penarikan Tunai Mandiri di Kios

1. Santri menempelkan kartu RFID ke mesin kios (harus bertipe kios penarikan & berstatus aktif).
2. Sistem menampilkan saldo & sisa limit penarikan harian.
3. Santri memasukkan nominal - jika sesuai kebijakan (saldo cukup, dalam jam operasional, dalam limit harian), sistem lanjut ke verifikasi sidik jari.
4. Santri menempelkan jari ke sensor - jika cocok dengan data yang terdaftar pada kartu tersebut, saldo didebit dan uang tunai keluar, tanpa perlu persetujuan petugas.
5. Jika nominal di luar kebijakan, atau verifikasi sidik jari gagal 3 kali berturut-turut, santri diarahkan untuk login dan mengajukan lewat jalur formal (unggah surat keterangan, review admin).

11.3 Wali Top Up Saldo via Midtrans (Mobile)

1. Wali membuka menu Top Up, memasukkan nominal, memilih metode (VA Bank atau QRIS).
2. Aplikasi menampilkan nomor Virtual Account atau kode QR langsung di layar.
3. Wali menyelesaikan pembayaran lewat aplikasi bank/e-wallet miliknya.
4. Sistem menerima notifikasi (webhook) dari Midtrans dan otomatis mengkredit 100% nominal ke saldo santri; wali juga dapat menekan "Cek Status Sekarang" untuk mempercepat sinkronisasi jika webhook belum sampai.

12. Integrasi Eksternal - Midtrans

Midtrans digunakan sebagai satu-satunya payment gateway, dengan dua mode integrasi:

• Snap (hosted checkout page) - digunakan di portal web wali untuk top up maupun pembayaran tagihan langsung; wali diarahkan ke halaman pembayaran Midtrans lalu kembali ke aplikasi.
• Core API (Virtual Account & QRIS langsung) - digunakan di aplikasi mobile (karena tidak ada WebView) dan tersedia juga sebagai opsi tambahan di web; nomor VA/kode QR ditampilkan langsung tanpa perlu membuka halaman eksternal.

Setiap transaksi Midtrans diberi prefix Order ID untuk membedakan tujuannya di dashboard Midtrans: TOPUP-... untuk top up saldo biasa, TAGIHAN-... untuk pembayaran tagihan langsung. Notifikasi (webhook) diverifikasi keasliannya lewat signature SHA-512 sebelum diproses, dan penanganannya bersifat idempoten (notifikasi duplikat untuk transaksi yang statusnya sudah final akan diabaikan).

13. Keamanan

• Buku besar tidak dapat diubah - setiap upaya mengubah/menghapus baris `Transaksi` akan ditolak sistem (`ImmutableLedgerException`), menjamin jejak audit keuangan tidak dapat dimanipulasi.
• Pemisahan tugas - bendahara tidak memiliki akses ke data kesantrian maupun pengaturan sistem; hanya admin yang dapat mengelola pengguna, perangkat, dan melakukan backup/restore.
• Verifikasi kepemilikan pada API mobile - setiap permintaan yang menyertakan ID santri divalidasi bahwa santri tersebut benar terhubung ke wali yang sedang login, tidak cukup hanya mengandalkan ID pada URL.
• Pembatasan laju (rate limiting) pada titik rawan - kios publik (pemindaian kartu & percobaan pencairan per santri) dan halaman login, untuk mencegah percobaan brute-force.
• Verifikasi ganda pada penarikan tunai mandiri - kartu fisik (something you have) dikombinasikan dengan sidik jari (something you are), setara dengan kekuatan otorisasi verifikasi petugas pada jalur formal sebelumnya.
• Konfirmasi eksplisit pada aksi keuangan - pembayaran tagihan dari saldo (web & mobile) selalu menampilkan rincian dan meminta konfirmasi tegas sebelum saldo benar-benar didebit, untuk menghindari ketukan/klik tidak sengaja.
• Autentikasi mobile berlapis (opsional) - token tersimpan aman di perangkat, dengan lapisan tambahan opsional berupa kunci sidik jari, penguncian instan saat aplikasi diminimalkan, dan auto-logout setelah 5 menit tidak aktif di latar depan (lihat 8.2).
• PIN transaksi sebagai lapis kedua khusus pemindahan saldo - terpisah dari kata sandi akun, menggerbangi tiga alur di aplikasi mobile: bayar tagihan dari saldo, bayar kantin, dan transfer antar santri. Verifikasi terkunci (`423 Locked`) selama 15 menit setelah 5 kali percobaan salah berturut-turut.

14. Keterbatasan & Utang Teknis Diketahui

Bagian ini didokumentasikan secara jujur agar tim yang melanjutkan pengembangan tidak perlu menemukan ulang batasan yang sudah diketahui:

• Fitur backup pernah mengalami kegagalan koneksi TCP/IP (Winsock error 10106) saat dijalankan dari proses web-server sungguhan di lingkungan Windows tertentu - penyebab pastinya belum berhasil diidentifikasi secara tuntas dan memerlukan investigasi lanjutan bila fitur ini akan diandalkan secara produksi.
• Cicilan hanya berlaku untuk pembayaran dari saldo, belum untuk pembayaran via Midtrans (baik Snap maupun Core API selalu menagih nominal penuh).
• Perangkat kantin fisik (`Device::TIPE_KANTIN`) ditautkan ke satu unit usaha dan memakai halaman /kios-kantin/{kode_device} untuk transaksi kartu RFID + sidik jari tanpa HP wali.
• Satu kegagalan test otomatis yang sudah dikonfirmasi tidak berkaitan dengan perubahan-perubahan terbaru (terkait urutan middleware CSRF pada skenario tertentu) - tercatat sebagai item terpisah yang belum diperbaiki.

15. Metrik Keberhasilan

Karena dokumen ini disusun retroaktif, metrik berikut diusulkan sebagai baseline untuk mengukur efektivitas sistem ke depan, bukan hasil yang sudah diukur:

• Adopsi wali - persentase wali aktif yang login & menggunakan aplikasi mobile/portal web dalam 30 hari terakhir.
• Rasio pembayaran non-tunai - persentase nilai tagihan yang dibayar lewat saldo/Midtrans dibanding tunai langsung ke admin.
• Tingkat swalayan kios - persentase penarikan tunai yang diselesaikan mandiri di kios tanpa perlu jalur formal/persetujuan petugas.
• Waktu penyelesaian tunggakan - rata-rata waktu antara tagihan dibuat dan dinyatakan lunas.
• Insiden rekonsiliasi - jumlah selisih/anomali saldo yang ditemukan per periode audit (target: nol, mengingat sifat buku besar yang tidak dapat diubah).

16. Rencana Pengembangan Lanjutan

• Dukungan cicilan untuk pembayaran via Midtrans, bukan hanya dari saldo.
• Tombol unduh mobile khusus kwitansi tagihan yang dibayar via Midtrans langsung (transfer_wali_tagihan); kwitansinya sudah diterbitkan di server dan dapat dicetak admin.
• Investigasi & perbaikan tuntas untuk isu koneksi pada fitur backup di lingkungan produksi.
• Evaluasi kebutuhan integrasi perangkat kios native/tertanam lewat jalur `/api/kiosk/*` yang sudah disiapkan namun belum dipakai secara aktif.

17. Glosarium

Lampiran A - Peta Rute Aplikasi Web (Ringkas)

Lampiran B - Daftar Endpoint API Mobile (/api/wali/*)