GURU-MU-Absensi-siswa

GURU MU — Absensi Siswa Otomatis

Aplikasi absensi sekolah berbasis Flask dan SQLite. Guru masuk melalui sesi server yang aman, mengelola siswa, membuka sesi absensi per tanggal/kelas, memindai QR Code unik, mencatat perubahan status, serta mengunduh rekap Excel dan PDF.

Fitur

• Login admin tanpa pendaftaran publik, hash password dengan Werkzeug, cookie sesi Secure/HttpOnly/SameSite, token CSRF, pembatasan percobaan login, sesi delapan jam, dan logout.
• Lima percobaan salah untuk kombinasi IP/username atau 15 percobaan dari satu IP memicu pembatasan login selama 15 menit.
• Ganti password tersedia secara opsional di Pengaturan; login pertama langsung membuka dashboard. Password baru minimal 12 karakter dan memakai sekurang-kurangnya tiga jenis karakter.
• Dashboard statistik hari ini, diperbarui ketika data berubah dan dimuat ulang otomatis berkala.
• Tambah, edit, cari, filter, dan hapus siswa (penghapusan mempertahankan riwayat); NIS dan QR Code unik.
• Cetak satu atau semua kartu siswa dengan QR Code yang tokennya divalidasi di backend.
• Sesi absensi per tanggal dan kelas; buka/tutup sesi, kamera dengan pemindai native BarcodeDetector dan pemindai cadangan lokal jsQR, serta input kode manual untuk pengujian.
• Status HADIR, IZIN, SAKIT, ALPA, dan BELUM ABSEN; perubahan status tercatat bersama waktu dan pengguna.
• Rekap harian, mingguan, dan bulanan, dengan filter kelas/nama/NIS, ekspor Excel/PDF, serta cetak dari browser.
• Database SQLite lokal yang tersimpan di instance/attendance.db; data tidak bergantung pada localStorage.

Persyaratan

• Windows 10/11 dan Python 3.10 atau lebih baru.
• Browser modern; akses kamera memerlukan izin browser. Kamera biasanya hanya tersedia di localhost atau situs HTTPS.

Instalasi Windows

Buka PowerShell di folder proyek:

py -3.10 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Copy-Item .env.example .env
notepad .env

Pada peluncuran pertama, isi .env dengan kredensial admin awal berikut. Password hanya dibaca oleh backend saat membuat akun pertama dan disimpan ke database dalam bentuk hash; tidak dikirim atau disematkan ke frontend.

ADMIN_USERNAME=GURU MU
ADMIN_PASSWORD=MASUK AJA123
SECRET_KEY=GANTI_DENGAN_HASIL_GENERATOR_RAHASIA_MINIMAL_32_KARAKTER

Ganti nilai SECRET_KEY dengan nilai acak yang rahasia sebelum dipakai bersama pengguna lain. Contoh untuk membuatnya di PowerShell:

python -c "import secrets; print(secrets.token_urlsafe(48))"

Salin hasilnya ke .env. Pastikan file .env tidak dibagikan; file tersebut diabaikan oleh Git. Aplikasi menolak nilai SECRET_KEY yang masih berupa placeholder atau kurang dari 32 karakter. Login pertama langsung menuju dashboard tanpa mewajibkan ganti password. Ganti password secara opsional melalui Pengaturan; password baru minimal 12 karakter dan harus mencakup setidaknya tiga jenis karakter: huruf kecil, huruf besar, angka, dan simbol.

Jalankan server lokal:

python app.py

Buka http://127.0.0.1:5000 dan masuk dengan username GURU MU serta password awal MASUK AJA123. Server membuat tabel dan admin saat pertama kali dijalankan. Jika admin sudah ada, mengubah nilai ADMIN_PASSWORD di .env tidak mengganti password database; gunakan menu Pengaturan.

Untuk menjalankan sebagai server WSGI di Windows:

waitress-serve --host=127.0.0.1 --port=5000 app:app

Untuk penggunaan di jaringan sekolah, pasang aplikasi di belakang reverse proxy HTTPS, gunakan host jaringan yang sesuai, buat SECRET_KEY yang rahasia, dan pertahankan COOKIE_SECURE=1 pada .env agar cookie login hanya dikirim melalui HTTPS. Jika menguji melalui HTTP biasa pada alamat selain localhost, browser dapat menolak cookie Secure; gunakan HTTPS, atau set COOKIE_SECURE=0 hanya untuk pengujian lokal pada jaringan tepercaya. Jangan mempublikasikan server Flask development (python app.py) ke internet. Login tidak menyediakan registrasi akun publik; batasi akses jaringan server kepada guru dan operator yang berwenang.

Deploy publik ke Render

Repositori ini dapat dideploy sebagai Blueprint Render menggunakan render.yaml. Konfigurasi membuat web service Python di region Singapore, menjalankannya dengan Waitress, mengaktifkan HTTPS-only cookies, serta menyimpan SQLite di disk persisten /var/data. Disk persisten memerlukan paket Render berbayar dan mencegah data hilang saat service restart atau deploy.

1. Push branch main ke GitHub dan pastikan repositori berisi render.yaml.
2. Buat akun Render, pilih New → Blueprint, lalu hubungkan repositori GitHub ini.
3. Saat diminta, isi ADMIN_USERNAME dan ADMIN_PASSWORD. Gunakan password unik yang panjang (sekurang-kurangnya 12 karakter dengan minimal tiga jenis karakter), bukan password contoh lokal MASUK AJA123. Jangan menaruh secret di file atau commit.
4. Biarkan Render membuat SECRET_KEY acak dan membuat disk persisten sesuai konfigurasi. Periksa ringkasan Blueprint, lalu setujui pembuatan service dan disk berbayar.
5. Tunggu deploy berstatus Live, lalu buka URL https://guru-mu-absensi.onrender.com (atau URL yang ditampilkan Render). Endpoint pemeriksaan kesehatan adalah /healthz.
6. Login dengan kredensial yang dimasukkan saat membuat Blueprint, lalu tambahkan siswa. Akses kamera melalui HTTPS dan izinkan penggunaan kamera pada browser/perangkat.

Jika akun admin sudah tercipta di database, mengubah ADMIN_PASSWORD pada environment Render tidak mengubah password tersimpan. Ganti password melalui Pengaturan saat masih login. Backup SQLite secara berkala dari disk persisten dan batasi akses Render/GitHub kepada operator berwenang. Jangan memakai SQLite yang sama dari beberapa instance aplikasi; disk Render terpasang hanya pada satu instance.

Lokasi dan konfigurasi database

Default: instance/attendance.db. Folder instance dibuat saat aplikasi berjalan dan diabaikan oleh Git. Untuk memilih lokasi lain, tetapkan DATABASE_PATH pada .env, misalnya DATABASE_PATH=D:/data/guru-mu/attendance.db. Buat backup database secara berkala; hentikan atau backup secara konsisten saat aplikasi sedang menulis data.

Alur penggunaan

1. Masuk ke dashboard dan tambah siswa. NIS setiap siswa harus unik.
2. Buka Scan Absensi, pilih tanggal dan kelas, lalu Buka Sesi.
3. Izinkan kamera dan arahkan ke QR Code kartu siswa. Aplikasi menggunakan pemindai QR native bila tersedia dan pemindai cadangan lokal bila tidak. Akses kamera membutuhkan HTTPS atau localhost. Input token QR manual tersedia untuk pengujian.
4. Status HADIR disimpan satu kali per siswa/sesi. Scan ulang akan menampilkan peringatan tanpa membuat catatan ganda.
5. Ubah status menjadi IZIN, SAKIT, atau ALPA dari daftar kelas; catatan perubahan akan terlihat di riwayat audit.
6. Tutup sesi untuk menghentikan pemindaian. Siswa yang belum dipindai tetap BELUM ABSEN sampai guru menetapkan status.
7. Gunakan Rekap Absensi untuk meninjau data tersimpan, mengunduh XLSX/PDF, atau mencetak laporan.
8. Gunakan Kartu Siswa untuk mencetak kartu individu maupun seluruh siswa/kelas yang terpilih.

Pengujian

Dengan virtual environment yang aktif dan dependensi sudah terpasang:

python -m unittest discover -v

Pengujian meliputi autentikasi dan hash password, akses admin, keunikan NIS, pembuatan sesi, validasi QR, pencegahan scan ganda, audit status, laporan, dan ekspor Excel/PDF. Test menggunakan database sementara dan tidak mengubah database aplikasi.

Struktur proyek

app.py                 Flask API, autentikasi, skema SQLite, QR dan ekspor
templates/index.html   Halaman login dan dashboard admin
static/css/style.css   Tampilan responsif
static/js/app.js       Interaksi frontend, kamera dan API
static/vendor/jsQR.js  Pemindai QR cadangan lokal (lisensi Apache-2.0)
static/vendor/jsQR-LICENSE.txt  Lisensi jsQR
requirements.txt       Dependensi Python
test_app.py            Pengujian API dan database
instance/              Database dan secret key lokal (tidak di-commit)

SQLite sesuai untuk instalasi sekolah kecil/satu server. Untuk beban multi-server atau konkurensi tinggi, migrasikan database ke PostgreSQL dan gunakan deployment serta TLS terkelola.