# PANDUAN LENGKAP INTEGRASI REAL-TIME MESIN FINGERSPOT & LARAVEL WEB APP
**Sistem Informasi Absensi & Monitoring Biometrik (Guru & Siswa)**

> **Powered by SyntaxTrust**  
> *Versi 1.0 — Dokumentasi Produksi & Manual Penggunaan Sistem*

---

## DAFTAR ISI
1. [Gambaran Umum Arsitektur (Architecture Overview)](#1-gambaran-umum-arsitektur)
2. [Langkah 1: Konfigurasi Jaringan & Mesin Fisik](#2-langkah-1-konfigurasi-jaringan--mesin-fisik)
3. [Langkah 2: Pengaturan Aplikasi Fingerspot Personnel](#3-langkah-2-pengaturan-aplikasi-fingerspot-personnel)
4. [Langkah 3: Konfigurasi & Menjalankan Local Connector Agent](#4-langkah-3-konfigurasi--menjalankan-local-connector-agent)
5. [Langkah 4: Pemetaan Data Siswa/Guru & Pengoperasian Web Laravel](#5-langkah-4-pemetaan-data-siswaguru--pengoperasian-web-laravel)
6. [Langkah 5: Skalabilitas Multi-Mesin (2 hingga 10+ Mesin)](#6-langkah-5-skalabilitas-multi-mesin-2-hingga-10-mesin)
7. [Troubleshooting & Solusi Kendala (FAQ)](#7-troubleshooting--solusi-kendala-faq)

---

<a name="1-gambaran-umum-arsitektur"></a>
## 1. GAMBARAN UMUM ARSITEKTUR

Sistem absensi ini menggunakan arsitektur **Local Hybrid Sync Connector**, yang menghubungkan mesin sidik jari fisik di sekolah dengan aplikasi web berbasis cloud/server tanpa membutuhkan biaya langganan cloud Fingerspot harian/bulanan.

```
┌───────────────────────────┐      Kabel LAN      ┌──────────────────────────────┐
│  Mesin Fingerspot Revo    │ ──────────────────> │ PC Gateway Lokal Sekolah     │
│  (IP: 192.168.0.50:8080)  │  (Download Log/Sync)│ (Aplikasi Fingerspot Personnel)│
└───────────────────────────┘                     └──────────────┬───────────────┘
                                                                 │ Database MySQL Port 3309 (fin_pro)
                                                                 ▼
┌───────────────────────────┐      HTTPS Push     ┌──────────────────────────────┐
│ Web Application Laravel   │ <────────────────── │ Local Connector Agent        │
│ (demo-absen-smk...)       │   (Tiap 10 Detik)   │ (node src/agent.js)          │
└───────────────────────────┘                     └──────────────────────────────┘
```

### Keunggulan Utama Sistem:
- **0 Biaya Langganan Cloud:** Menggunakan jaringan lokal dan database PC gateway.
- **Toleransi Offline (Offline Queue):** Jika koneksi internet terputus, data scan tetap tersimpan aman di PC dan dikirim otomatis saat internet tersambung kembali.
- **Real-Time Processing:** Log absensi diolah dalam 5-10 detik menjadi rekapitulasi Hadir, Terlambat, atau Alpha untuk Siswa dan Guru.
- **Dukungan Multi-Mesin:** Mampu menangani dari 1 hingga 10+ mesin fingerprint secara bersamaan tanpa mengubah kode.

---

<a name="2-langkah-1-konfigurasi-jaringan--mesin-fisik"></a>
## 2. LANGKAH 1: KONFIGURASI JARINGAN & MESIN FISIK

### A. Pengaturan IP Kartu LAN Komputer Gateway (PC Sekolah):
- **IP Address:** `192.168.0.100` (Statis)
- **Subnet Mask:** `255.255.255.0`
- **Gateway:** `192.168.0.1`

### B. Pengaturan Layar Mesin Fingerspot (Fingerspot Revo W-230N):
1. Tekan tombol **[ MENU / OK ]** pada mesin fisik.
2. Masuk ke menu **Comm / Komunikasi / Jaringan** -> **Ethernet**.
3. Atur parameter jaringan mesin:
   - **IP Address:** `192.168.0.50`
   - **Subnet Mask:** `255.255.255.0`
   - **Gateway:** `192.168.0.1`
   - **Comm Port:** `8080` (atau `4370`)
4. Tekan **Simpan** dan **Restart / Matikan Ulang Mesin**.

### C. Pengujian Jaringan dari PC Windows:
Buka Command Prompt (CMD) di PC dan ketik:
```cmd
ping 192.168.0.50
```
*Pastikan balasan menunjukkan `Reply from 192.168.0.50: bytes=32 time<5ms TTL=64`.*

---

<a name="3-langkah-2-pengaturan-aplikasi-fingerspot-personnel"></a>
## 3. LANGKAH 2: PENGATURAN APLIKASI FINGERSPOT PERSONNEL

Aplikasi **Fingerspot Personnel** di PC bertugas menarik data dari mesin dan menyimpannya di database MySQL lokal (`fin_pro`).

### A. Memastikan IP Mesin di Aplikasi Sesuai:
1. Buka aplikasi **Fingerspot Personnel** di Windows.
2. Masuk ke tab **Mesin** -> Klik **Pengaturan Mesin** (atau klik 2x nama mesin).
3. Ubah pengaturan:
   - **IP Address / URL:** `192.168.0.50`
   - **Port:** `8080`
4. Klik **Simpan**.

### B. Mengaktifkan Auto Download (100% Otomatis Tanpa Tekan Tombol Manual):
1. Masuk ke menu **Pengaturan** -> **Pengaturan Otomatis / Auto Download**.
2. Centang **Aktifkan Download Otomatis**.
3. Set interval penarikan (misal: setiap 1 menit / 5 menit).
4. Klik **Simpan**.

*Informasi Database Internal Fingerspot Personnel:*
- **Engine Database:** MySQL 5.1 (Embedded Port `3309`)
- **Nama Database:** `fin_pro` (Tabel utama: `att_log`, `device`, `pegawai`)
- **Username / Password:** `root` / `Coba lagi lain kali 2015`

---

<a name="4-langkah-3-konfigurasi--menjalankan-local-connector-agent"></a>
## 4. LANGKAH 3: KONFIGURASI & MENJALANKAN LOCAL CONNECTOR AGENT

Local Connector Agent adalah service Node.js yang membaca database `fin_pro` dan mengirim data absensi ke web Laravel.

### A. Lokasi Folder Agent di PC:
`C:\laragon\www\absen\local-connector`

### B. Konfigurasi File `.env`:
Buka file `.env` di dalam folder `local-connector` dan pastikan isinya:
```ini
# URL Server Web Laravel
LARAVEL_API_URL=https://demo-absen-smk.syntaxtrust.web.id

# Secret Token Autentikasi
CONNECTOR_TOKEN=SK_LNK_SMKN1_9238491823
```

### C. Cara Menjalankan Agent di PC Windows:
1. Buka Command Prompt (CMD) atau Cmder.
2. Jalankan perintah:
   ```cmd
   cd C:\laragon\www\absen\local-connector
   node src/agent.js
   ```
3. Terminal akan menampilkan pesan:
   ```
   ╔══════════════════════════════════════════════════════╗
   ║ Local Connector Agent — Production DB Syncer Active ║
   ╠══════════════════════════════════════════════════════╣
   ║ Database Source: MySQL 127.0.0.1:3309 (fin_pro)     ║
   ║ Laravel Server : https://demo-absen-smk.syntaxtrust.web.id
   ╚══════════════════════════════════════════════════════╝
   
   [PUSH_SUCCESS] 🎉 Record absensi BERHASIL TERKIRIM KE LARAVEL!
   ```

---

<a name="5-langkah-4-pemetaan-data-siswaguru--pengoperasian-web-laravel"></a>
## 5. LANGKAH 4: PEMETAAN DATA SISWA/GURU & PENGOPERASIAN WEB LARAVEL

Agar data scan jari dari mesin dapat **dicocokkan 100% akurat** dengan nama Siswa dan Guru di web Laravel, ikuti panduan berikut:

### A. Aturan Pemetaan PIN (Sangat Penting):
> **Nomor PIN User di Mesin/Fingerspot = Kolom `PIN Fingerprint` / `NIP` / `NIS` di Web Laravel**

#### 1. Untuk Data Guru:
- Buka Web Laravel -> Menu **Data Guru & Siswa** / **Management User**.
- Edit data Guru -> Pada kolom **PIN Fingerprint** (atau **NIP**), masukkan nomor PIN yang didaftarkan di mesin/Fingerspot Personnel (contoh: PIN `10` untuk *Ahmad Fauzi, S.T.*).

#### 2. Untuk Data Siswa:
- Buka Web Laravel -> Menu **Data Guru & Siswa**.
- Edit data Siswa -> Pada kolom **PIN Fingerprint** (atau **NIS/NISN**), masukkan nomor PIN yang didaftarkan di mesin/Fingerspot Personnel (contoh: PIN `12` untuk *Andi Pratama*).

### B. Memantau Status Agent & Kehadiran di Dashboard:
1. Masuk ke Dashboard Utama (`/dashboard`).
2. Banner **Local Connector Agent: ONLINE (ACTIVE)** berwarna hijau menandakan koneksi agent dari PC sekolah terhubung lancar.
3. Grafik Kehadiran Mingguan & Heatmap Kehadiran 30 Hari akan otomatis memperbarui statistik Hadir, Terlambat, dan Alpha.

### C. Melihat Riwayat Absensi & Audit Log:
1. **Laporan Kehadiran (`/reports`):** Menampilkan rekapitulasi kehadiran Guru & Siswa lengkap dengan filter tanggal, kelas, dan status (Hadir/Terlambat/Alpha).
2. **Monitoring Aplikasi (`/system-monitoring`):** Menampilkan audit log mentah (Raw Log) yang diterima dari Agent beserta timestamp dan status pemrosesan.

---

<a name="6-langkah-5-skalabilitas-multi-mesin-2-hingga-10-mesin"></a>
## 6. LANGKAH 5: SKALABILITAS MULTI-MESIN (2 HINGGA 10+ MESIN)

Sistem telah mendukung penambahan hingga **10+ mesin fingerprint** di tempat yang berbeda (misal: Ruang Guru, Gerbang Depan, Bengkel TKR, Lab Komputer) tanpa perlu merubah kodingan agent.

### Cara Menambah Mesin Baru di Masa Depan:
1. **Di PC Sekolah (Fingerspot Personnel):**
   - Buka Fingerspot Personnel -> Tambah Mesin Baru -> Masukkan IP & Nama Mesin.
2. **Di Agent PC (`local-connector`):**
   - **TIDAK PERLU EDIT APAPUN.** File `.env` dan `agent.js` akan otomatis mengambil seluruh log dari semua mesin yang terdaftar di Fingerspot Personnel.
3. **Di Web Laravel (`/machines`):**
   - Masuk ke menu **Mesin Fingerprint** (`/machines`) -> Klik **Tambah Mesin Baru** -> Masukkan Nama Mesin & Serial Number / IP-nya.

---

<a name="7-troubleshooting--solusi-kendala-faq"></a>
## 7. TROUBLESHOOTING & SOLUSI KENDALA (FAQ)

### Q1: Kenapa status Agent di Dashboard menunjukkan OFFLINE?
- **Penyebab:** Perintah `node src/agent.js` di PC sekolah mati atau PC terputus dari internet.
- **Solusi:** Buka CMD di PC sekolah dan jalankan kembali `node src/agent.js`.

### Q2: Aplikasi Fingerspot Personnel menampilkan error "Tidak bisa terhubung dengan mesin"?
- **Penyebab:** IP mesin di aplikasi Fingerspot Personnel berbeda dengan IP asli mesin.
- **Solusi:** Buka Fingerspot Personnel -> Mesin -> Pengaturan Mesin -> Ubah IP Address menjadi `192.168.0.50` dan Port `8080`.

### Q3: Kenapa setelah scan jari, nama Siswa/Guru belum muncul di Laporan Kehadiran?
- **Penyebab:** Nomor PIN di mesin belum diinput pada data Siswa/Guru di web.
- **Solusi:** Periksa nomor PIN siswa/guru tersebut di mesin/Fingerspot Personnel, lalu masukkan PIN tersebut ke kolom **PIN Fingerprint** pada menu Data Guru & Siswa di Web Laravel.

### Q4: Apakah data absensi hilang jika internet sekolah mati seharian?
- **TIDAK.** Agent memiliki fitur **Local Queue System**. Semua data scan jari disimpan aman di memori PC dan akan langsung terkirim otomatis ke server Laravel begitu internet terhubung kembali.

---

*Dokumentasi Resmi Sistem Absensi Fingerprint Real-Time*  
**Powered by SyntaxTrust**  
*https://syntaxtrust.web.id*
