Sistem Absensi Fingerprint Sekolah dengan Laravel Filament & C# WinForms

Irman Firmansyah
Irman Firmansyah

Daftar isi

Latar Belakang

Dokumentasi ini merangkum proses pembuatan Sistem Absensi Sekolah berbasis Fingerprint, mulai dari nol sampai siap dipasang di sekolah. Sistem ini terdiri dari dua bagian:

  • Aplikasi Web (Backend) — dibangun pakai Laravel 13 + Filament (panel admin) + Sanctum (API), untuk manajemen data siswa, perangkat, dan laporan absensi (harian & rekap semester).
  • Aplikasi Client Desktop — dibangun pakai C# WinForms di Visual Studio 2022, terhubung ke sensor fingerprint DigitalPersona U.are.U 4500 lewat SDK DPUruNet/DPCtlUruNet, dan berkomunikasi ke backend lewat REST API (Sanctum token).

Alur bisnisnya: proses enroll (registrasi sidik jari) dan verifikasi/absensi sepenuhnya dilakukan di aplikasi client desktop. Begitu sidik jari cocok, aplikasi client cuma mengirim student_id ke server, lalu server yang menentukan tanggal & jam absen (berdasarkan waktu server, bukan jam PC client, supaya tidak bisa dimanipulasi).

Arsitektur Singkat

[Sensor Fingerprint U.are.U 4500]
        │
        ▼
[Aplikasi Client C# WinForms]  ← proses enroll & identify 1:N sidik jari terjadi di sini
        │  (HTTP + Sanctum Token per-device)
        ▼
[Laravel API (routes/api.php)]
        │
        ▼
[Database MySQL] ← dikelola lewat [Panel Admin Filament]

Source code lengkap: https://github.com/irmanf11/absensi-fingerprint

Bagian 1 — Setup Backend Laravel + Filament + Sanctum

1.1 Buat Project Laravel

composer create-project laravel/laravel school-attendance
cd school-attendance

1.2 Install Sanctum (API)

php artisan install:api

Perintah ini otomatis menambahkan routes/api.php, migration personal_access_tokens, dan mendaftarkan routing API di bootstrap/app.php.

1.3 Install Filament (WAJIB versi 3.x)

Catatan penting: kalau install tanpa versi spesifik, Composer akan menarik Filament v4 yang strukturnya beda jauh (form builder pindah ke package Schemas, tipe properti navigasi berubah, dll) dan akan bikin error fatal kalau dipasangkan dengan kode di source code ini yang ditulis untuk Filament v3. Pastikan pin versi seperti di bawah.
composer require "filament/filament:^3.3" -W
php artisan filament:install --panels
php artisan make:filament-user

1.4 Copy File dari Source Code

Salin seluruh isi folder backend/ dari source code (migration, model, controller, resource Filament, widget dashboard, view) ke project Laravel baru Anda, dengan struktur folder yang sama persis.

1.5 Setup Database & Migrate

Isi kredensial database di .env, lalu:

php artisan migrate

1.6 Set Timezone & Bahasa Indonesia

Di config/app.php, ubah:

'timezone' => 'Asia/Jakarta',
'locale' => 'id',
'faker_locale' => 'id_ID',

Lalu:

php artisan config:clear

Timezone ini penting karena tanggal & jam absensi ditentukan lewat now() di server — kalau tidak diubah dari default UTC, jam absen akan tercatat selisih 7 jam dari WIB.

1.7 Buat Device & Ambil Token API

  1. Login ke /admin
  2. Buka menu Perangkat Absensi → tambah device baru (isi nama & lokasi, misal "Absensi Gerbang Utama")
  3. Klik tombol Generate Token pada device tersebut
  4. Salin token yang muncul (hanya tampil sekali!) — token ini nanti dipakai di App.config aplikasi client

1.8 Dashboard Admin

Supaya dashboard tidak kosong, folder app/Filament/Widgets/ berisi 3 widget yang otomatis terdeteksi Filament:

  • AttendanceOverview.php — kartu statistik (Total Siswa, Hadir Hari Ini, Belum Enroll Fingerprint)
  • WeeklyAttendanceChart.php — grafik tren absensi 7 hari terakhir
  • LatestAttendances.php — tabel 10 absensi terbaru

Kalau folder app/Filament/Widgets/ belum ada di project Anda, tinggal buat manual:

mkdir -p app/Filament/Widgets

Bagian 2 — Setup Project Client Desktop di Visual Studio 2022

2.1 Install Visual Studio 2022

Download dari link resmi di atas, lalu saat instalasi pilih workload ".NET desktop development". Kalau Visual Studio sudah terinstall tapi template "Windows Forms App" tidak muncul, workload ini kemungkinan belum terpasang — buka Visual Studio Installer → Modify → centang workload tersebut.

2.2 Buat Project Baru

  1. Create a new project → cari template "Windows Forms App (.NET Framework)"
  2. Project name: SSBFingerprint (atau nama lain — sesuaikan namespace di semua file kalau beda)
  3. Framework: .NET Framework 4.8

2.3 Set Platform Target

Klik kanan project → Properties → tab Build → Platform target: pilih x86 (paling umum untuk SDK DigitalPersona) atau sesuaikan dengan versi SDK yang dipasang.

2.4 Tambahkan Reference SDK

Klik kanan References → Add Reference → Browse → cari DPUruNet.dll dan DPCtlUruNet.dll dari folder instalasi SDK DigitalPersona.

2.5 Tambahkan Reference System.Configuration

Diperlukan supaya ConfigurationManager (dipakai untuk baca App.config) bisa dipakai:

Klik kanan References → Add Reference → tab Assemblies > Framework → centang System.Configuration.

2.6 Install NuGet Package

Karena target .NET Framework 4.8, System.Text.Json tidak built-in:

Klik kanan project → Manage NuGet Packages → tab Browse → cari System.Text.Json → Install.

2.7 Copy File dari Source Code

Hapus Form1.cs bawaan, lalu tambahkan file-file dari folder client/SSBFingerprint/ di source code:

  • Program.cs
  • Form_Main.cs + Form_Main.Designer.cs
  • ReaderSelection.cs + ReaderSelection.Designer.cs
  • Form_Enroll.cs + Form_Enroll.Designer.cs
  • Form_Verify.cs + Form_Verify.Designer.cs
  • ApiService.cs
  • Models/StudentListItem.cs
  • App.config
Tips: dialog "Add Existing Item" secara default cuma menampilkan file .cs. Untuk file App.config, ganti filter tipe file di pojok kanan bawah dialog jadi "All Files (*.*)" supaya muncul dan bisa dipilih.

Kalau nama project/namespace Anda bukan SSBFingerprint, cara paling cepat menyesuaikan: klik kanan project → Properties → tab Application → Default namespace → isi SSBFingerprint (tidak perlu edit satu-satu file).

Atau bisa juga replace semua namespace SSBFingerprint bawaan dari folder client/SSBFingerprint/ dan ganti dengan nama namespace yang Anda buat.

2.8 Edit App.config

<appSettings>
  <add key="ApiBaseUrl" value="https://domain-sekolah-anda.com/api/" />
  <add key="ApiToken" value="TOKEN_DARI_WEB_ADMIN" />
</appSettings>

Jika mau menggunakan link local Laravel bisa gunakan http://127.0.0.1:8000/

2.9 Build & Test

Set Startup object di Project Properties → Application → pastikan project menjalankan Program.cs (Main entry point) yang langsung membuka Form_Main. Tekan F5 untuk test.

2.10 Fitur Mode Antrian (Auto-Capture)

Menu Absensi Siswa didesain untuk skenario siswa antri: begitu form dibuka, sensor otomatis "mendengarkan" terus-menerus tanpa perlu klik tombol scan setiap siswa. Siswa tinggal tempel jari bergantian, hasil (Hadir / Sudah Absen / Tidak Dikenali) langsung muncul, lalu sensor otomatis siap lagi untuk siswa berikutnya setelah jeda ±1.2 detik. Ada tombol Mulai/Jeda Antrian kalau operator perlu menghentikan sementara.

Bagian 3 — Build Release & Bikin Installer (Inno Setup)

3.1 Build Konfigurasi Release

  1. Di toolbar Visual Studio, ganti dropdown konfigurasi dari Debug ke Release
  2. Menu Build → Build Solution (atau Rebuild Solution kalau sebelumnya pernah build Debug)
  3. Hasil build ada di folder bin\Release\ di dalam folder project — ini berisi SSBFingerprint.exe, SSBFingerprint.exe.config, dan semua DLL yang dibutuhkan (termasuk DPUruNet.dll, DPCtlUruNet.dll)

3.2 Install Inno Setup

Download & install dari link resmi di atas (pilih versi stabil terbaru).

3.3 Compile Installer

Source code sudah menyertakan script siap pakai di client/installer/SSBFingerprint.iss. Cara pakai:

  1. Buka file SSBFingerprint.iss dengan Inno Setup
  2. Cek baris #define SourceDir "..\SSBFingerprint\bin\Release" — sesuaikan path-nya kalau struktur folder project Anda berbeda
  3. Menu Build → Compile (atau Ctrl+F9)
  4. Hasil installer (SetupAbsensiFingerprint_v1.0.exe) muncul di folder installer\Output\

Script ini sudah diatur supaya tidak menimpa App.config yang sudah diisi token kalau aplikasi di-install ulang/update di komputer yang sama — jadi operator tidak perlu setting ulang token API tiap kali update versi aplikasi.

Bagian 4 — Instalasi di Laptop/PC Sekolah (Komputer Client)

Di komputer sekolah yang dipasangi sensor fingerprint, tidak perlu install SDK lengkap (SDK cuma dibutuhkan di komputer development untuk compile aplikasi). Yang perlu diinstall di PC sekolah cuma:

4.1 Driver Fingerprint (Non-WBF)

Download & install driver dari link HID Global di atas. Pastikan pilih versi Non-WBF (bukan WBF/Windows Biometric Framework) supaya kompatibel dengan SDK DPUruNet yang dipakai aplikasi ini.

4.2 Runtime Environment (RTE)

Dari paket SDK DigitalPersona yang di-download (link archive.org di atas), ada installer terpisah untuk Runtime Environment (folder "RTE" atau serupa) — ini yang perlu diinstall di PC sekolah, bukan paket SDK development lengkap. Runtime ini menyediakan service & library yang dibutuhkan aplikasi untuk berkomunikasi dengan sensor saat runtime, tanpa perlu tools development.

4.3 Install Aplikasi Client

Jalankan file installer hasil compile Inno Setup (SetupAbsensiFingerprint_v1.0.exe) di PC sekolah, ikuti wizard instalasinya.

4.4 Konfigurasi Awal

Buka folder instalasi aplikasi, edit SSBFingerprint.exe.config (kalau belum otomatis terisi), isi ApiBaseUrl dan ApiToken sesuai device yang sudah dibuat di panel admin.

4.5 Test Koneksi

Buka aplikasi → pilih reader → coba menu Enroll dengan 1 siswa dulu untuk memastikan koneksi ke server jalan, baru lanjut proses enroll massal siswa lainnya.

Bagian 5 — Deploy Laravel ke Hosting

Untuk deploy backend Laravel ke shared hosting (tanpa VPS, tanpa SSH), ikuti panduan lengkap yang sudah saya tulis terpisah di sini:

Cara Deploy Laravel ke Shared Hosting Tanpa VPS dan Tanpa SSH

Poin tambahan khusus untuk sistem ini:

  • Pastikan PHP versi minimal 8.1 (rekomendasi 8.2+) aktif di hosting — banyak shared hosting default-nya masih PHP versi lama, cek & ganti dulu di cPanel sebelum upload
  • Ekstensi PHP yang wajib aktif: mbstring, openssl, pdo, pdo_mysql, tokenizer, xml, ctype, json, bcmath, fileinfo
  • Setelah upload, akses /admin untuk memastikan panel Filament jalan, lalu buat device & token API baru untuk dipakai di aplikasi client production

Troubleshooting yang Pernah Ditemui

ErrorPenyebab & Solusi
Type of $navigationGroup must be UnitEnum|string|null Ke-install Filament v4 padahal kode ditulis untuk v3. Solusi: composer require "filament/filament:^3.3" -W
The name 'ConfigurationManager' does not exist in the current context Assembly System.Configuration belum di-reference. Tambahkan lewat Add Reference → Assemblies → Framework.
Feature 'using declarations' is not available in C# 7.3 Project .NET Framework default pakai C# 7.3. Solusi: ganti using var x = ...; jadi using (var x = ...) { }, atau set <LangVersion>8.0</LangVersion> di file .csproj.
Template "Windows Forms App" tidak muncul di New Project Workload .NET desktop development belum terpasang. Buka Visual Studio Installer → Modify → centang workload tersebut.
Dialog "Add Existing Item" tidak menampilkan App.config Ganti filter tipe file di dialog dari default (*.cs) ke All Files (*.*).
Tidak perlu pakai nama SSBFingerprint Ganti namespace ini di Visual Studio 2022 dan sesuaikan dengan kebutuhan.

Penutup

Dengan dokumentasi ini, seluruh proses dari nol — bikin backend, bikin client desktop, build installer, sampai instalasi di PC sekolah dan deploy ke hosting — sudah tercatat lengkap. Saya simpan catatannya disini biar gak lupa, dan mungkin bisa bermanfaat juga untuk siapapun yang sedang bergelut dengan project fingerprint.

Lebih lamaTerbaru

Related Posts

Memuat…

Posting Komentar