# Panduan Instalasi & Operasional Local Connector Agent

Sistem Absensi "Pull & Push" Terintegrasi (Node.js ke Laravel)  
**Dokumen ditujukan untuk:** Teknisi Jaringan, Staf Tata Usaha, dan Operator Sekolah.

---

## 1. Topologi Jaringan Lapangan

Sistem ini menggunakan arsitektur **Pull & Push**, artinya komputer lokal di sekolah berfungsi sebagai **Gateway / Jembatan (Bridge)** yang menarik data dari mesin secara mandiri, lalu mengunggahnya (*Push*) ke server pusat di internet secara waktu nyata (*real-time*).

### Skema Fisik Jaringan
```text
[Mesin Fingerprint 1] --\
[Mesin Fingerprint 2] ---\
[Mesin Fingerprint 3] ----\
[Mesin Fingerprint 4] -----> [ HUB / SWITCH LOKAL ] -----> [ KOMPUTER GATEWAY ]
[Mesin Fingerprint 5] ----/                                     (Menjalankan Node.js)
[Mesin Fingerprint 6] ---/                                             |
                                                                       | (Jalur Internet Terpisah)
                                                                       V
                                                               [ SERVER HOSTING PUBLIC ]
                                                          (https://demo-absen-smk.syntaxtrust.web.id)
```

### Konfigurasi Dual Koneksi (Penting!)
Komputer Gateway **wajib** memiliki 2 jalur koneksi yang aktif secara bersamaan:
1. **Jalur LAN (Lokal)**: Kabel LAN terhubung ke Hub/Switch lokal (dengan segmen IP statis misal: `192.168.1.xxx`) agar bisa berkomunikasi (melakukan PING) ke-6 mesin biometrik.
2. **Jalur Internet**: Komputer Gateway harus terhubung ke internet (via WiFi, Modem USB, atau NIC LAN kedua) agar agen Node.js bisa mem-POST data ke server hosting.

---

## 2. Konfigurasi Environment (File `.env`)

Agar komputer lokal diizinkan berkomunikasi dengan server pusat, diperlukan penyamaan kunci token dan alamat IP.

### A. Sinkronisasi API Token
1. Di komputer **Server Hosting**, buka file `.env` di root Laravel dan pastikan terdapat kode token:
   ```env
   CONNECTOR_TOKEN=KunciRahasiaSekolah2026!
   ```
2. Di **Komputer Gateway Lokal**, buka folder `local-connector/` lalu buat atau edit file `.env`:
   ```env
   LARAVEL_API_URL=https://demo-absen-smk.syntaxtrust.web.id
   CONNECTOR_TOKEN=KunciRahasiaSekolah2026!
   ```
   *(Pastikan `CONNECTOR_TOKEN` sama persis agar sistem tidak menolak koneksi / Unauthorized)*

### B. Mendaftarkan IP Mesin Biometrik
1. Buka file skrip **`local-connector/src/agent.js`**.
2. Pada bagian atas file, pastikan Anda mendaftarkan IP statis ke-6 mesin di dalam blok array `MACHINES`:
   ```javascript
   const MACHINES = [
       '192.168.1.11',
       '192.168.1.12',
       '192.168.1.13',
       '192.168.1.14',
       '192.168.1.15',
       '192.168.1.16'
   ];
   ```

---

## 3. Cara Menjalankan & Menghentikan Agen (Mode Produksi)

Kami sangat menyarankan penggunaan **PM2** (Process Manager 2) agar agen tetap menyala (*always-on*) di balik layar, meskipun jendela CMD ditutup atau komputer tidak sengaja direstart (mati lampu).

### Persiapan Awal (Prasyarat Sistem)
Sebelum dapat menjalankan agen, komputer Gateway lokal Anda wajib memiliki:
1. **Node.js**: Unduh dan pasang versi terbaru (LTS) dari situs resmi [nodejs.org](https://nodejs.org).
2. Setelah Node.js terpasang, instal dependensi yang dibutuhkan (hanya untuk pertama kali). Buka CMD dan arahkan ke folder agen, lalu ketik:
   ```cmd
   cd C:\Jalur\Ke\sistem_absensi_fingerprint\local-connector
   npm install
   ```
3. (Opsional) Instal PM2 secara global jika Anda berencana menjalankan agen di belakang layar:
   ```cmd
   npm install -g pm2
   ```

### Langkah 1: Uji Coba Manual (Testing)
Sebelum memasukkan ke PM2, pastikan tidak ada error dengan menjalankannya secara manual:
1. Buka aplikasi **Command Prompt (CMD)** atau terminal.
2. Pindah ke direktori agen:
   ```cmd
   cd C:\Jalur\Ke\sistem_absensi_fingerprint\local-connector
   ```
3. Jalankan agen:
   ```cmd
   node src/agent.js
   ```
4. Jika di layar CMD muncul tulisan log berwarna sukses (ex: *"Mengirim X data absensi ke Laravel..."*), tekan **`Ctrl + C`** untuk mematikannya sementara.

### Langkah 2: Memasang Agen Secara Permanen (PM2)
Buka CMD (jalankan sebagai Administrator jika di Windows) lalu ketik:

1. **Memulai Agent via PM2:**
   ```cmd
   pm2 start src/agent.js --name "AbsensiConnector"
   ```
2. **Mengatur agar otomatis menyala saat komputer dihidupkan (Auto-Startup):**
   ```cmd
   pm2 startup
   ```
   *(Ikuti instruksi/perintah tambahan yang muncul di layar CMD setelah Anda mengetik perintah di atas)*
3. **Menyimpan konfigurasi saat ini:**
   ```cmd
   pm2 save
   ```

### Command Tambahan PM2
- Melihat status agen: `pm2 status`
- Melihat log (catatan error/sukses): `pm2 logs AbsensiConnector`
- Mematikan agen: `pm2 stop AbsensiConnector`
- Me-restart agen: `pm2 restart AbsensiConnector`

---

## 4. Troubleshooting Sederhana

Jika status mesin di Dashboard Web Anda tiba-tiba berubah menjadi **KUNING (STALE)** atau **MERAH (OFFLINE)**, operator lapangan dapat melakukan langkah-langkah P3K berikut:

1. **Cek Koneksi Listrik & Kabel LAN**
   Pastikan mesin biometrik menyala dan kabel LAN yang tertancap di komputer Gateway & Hub tidak kendor.
   
2. **Tes PING ke Mesin dari Komputer Gateway**
   Buka CMD, lalu ketik `ping 192.168.1.11` (Ganti dengan IP Mesin). Jika muncul tulisan *Reply from...*, berarti jaringan lokal aman. Jika *Request timed out*, berarti masalah ada di kabel/Hub lokal.

3. **Cek Koneksi Internet Komputer Gateway**
   Di CMD, ketik `ping google.com`. Jika berhasil, internet aman. Jika *Request timed out*, agen tidak akan bisa mengirim data. Periksa koneksi WiFi / Modem komputer lokal Anda.

4. **Cek Log Agen PM2**
   Buka CMD, ketik `pm2 logs AbsensiConnector`. Jika muncul tulisan `[PUSH_FAILED] Gagal mengirim data`, bisa jadi Kunci Token (Environment) tidak cocok atau URL API sedang terputus.

5. **Pantau Indikator Dashboard Pusat**
   Setiap kali agen PM2 di PC lokal berhasil mengunggah paket data, Kotak Indikator Status di halaman utama (Dashboard Website) akan **berkedip hijau (ONLINE)** disertai rentang waktu detik/menit log terakhir diterima.

---
*Dibuat & Dikelola secara otomatis oleh Sistem Integrasi Absensi 2026*  
**Powered by [syntaxtrust.web.id](https://syntaxtrust.web.id) - SyntaxTrust Web IT Solutions**
