# 🔌 LOCAL CONNECTOR AGENT FOR FINGERSPOT / ZKTECO
### **Sistem Absensi Fingerprint Terintegrasi (SMK Negeri 1 Gunung Agung)**

Local Connector Agent adalah service perantara (bridge) ringan yang berjalan pada PC Windows sekolah (IP `192.168.0.106`).
Service ini bertindak sebagai jembatan antara aplikasi **Fingerspot Personnel 2024 / Revo W-231N** di LAN sekolah dengan **Server Aplikasi Web Laravel** di hosting/cloud via outbound HTTPS.

---

## 🏗️ Arsitektur Jaringan (Outbound Push Model)

```text
┌───────────────────────────────────────────────────────────┐
│                    PC SEKOLAH (WINDOWS)                   │
│                                                           │
│  [ Revo W-231N ] ───(TCP 4370)───> [ Fingerspot Personnel ]│
│                                           │               │
│                                   (Scanlog Download)      │
│                                           ▼               │
│                            [ LOCAL CONNECTOR AGENT ]      │
└───────────────────────────────────────────────────────────┘
                                            │
                                (Outbound HTTPS POST)
                                            ▼
                        ┌───────────────────────────────────┐
                        │      SERVER WEB LARAVEL (CLOUD)   │
                        │  POST /api/connector/push-attlog  │
                        │  POST /api/connector/heartbeat    │
                        └───────────────────────────────────┘
```

> **Keuntungan Utama**:
> - **Aman**: Tidak memerlukan Port Forwarding atau membuka Port 4370 ke publik internet.
> - **Stabil**: Menggunakan token terenkripsi (`X-Connector-Token`) dan proteksi dari duplikasi log (*idempotent*).
> - **Ringan**: Berjalan sebagai Windows Background Service tanpa mengganggu Fingerspot Personnel 2024.

---

## 📋 Persyaratan Sistem

1. **OS**: Windows 10 / 11 / Windows Server 2016+
2. **Node.js**: v18.x atau v20.x LTS ([Download Node.js](https://nodejs.org/))
3. **Koneksi Jaringan**:
   - Terhubung ke LAN Sekolah (`192.168.0.106`)
   - Dapat mengakses Internet / URL Server Laravel Web App (`https://demo-absen-smk.syntaxtrust.web.id`)

---

## 🚀 Panduan Instalasi di PC Windows Sekolah

### Langkah 1: Copy Folder Agent
Copy folder `local-connector/` dari proyek ini ke PC Windows sekolah, misalnya diletakkan pada:
`C:\Services\local-connector\`

### Langkah 2: Install Dependensi
Buka **Command Prompt (cmd)** atau **PowerShell** sebagai Administrator, masuk ke folder agent, dan jalankan:
```cmd
cd C:\Services\local-connector
npm install
```

### Langkah 3: Konfigurasi File `.env`
Buat atau edit file `.env` di dalam folder `C:\Services\local-connector\.env`:

```ini
# URL Server Web Laravel
LARAVEL_API_URL=https://demo-absen-smk.syntaxtrust.web.id

# Secret Token Autentikasi (Sama dengan Connector Token di Web App)
CONNECTOR_TOKEN=SK_LNK_SMKN1_9238491823

# Identitas Mesin Sekolah
MACHINE_ID=1
MACHINE_IP=192.168.0.106
SERIAL_NUMBER=616231023290570

# Port Lokal untuk Diagnostics (/health)
LOCAL_PORT=8000

# Interval Sync (detik)
HEARTBEAT_INTERVAL_SECONDS=30
SCANLOG_POLL_INTERVAL_SECONDS=60
```

### Langkah 4: Uji Coba Jalankan Agent
Jalankan command berikut untuk memastikan agent berjalan dengan normal:
```cmd
node src/agent.js
```
Output log akan menampilkan:
`[INFO] Local Connector Agent started on port 8000`
`[INFO] Heartbeat sent to Laravel web server: SUCCESS`

Buka browser PC dan akses `http://localhost:8000/health` untuk memastikan response `/health` 200 OK.

---

## ⚙️ Memasang Agent Sebagai Windows Service (Auto-Start saat PC dinyalakan)

Agar agent otomatis berjalan di background saat PC Windows dinyalakan tanpa perlu membuka CMD manual, gunakan **NSSM (Non-Sucking Service Manager)** atau **pm2-windows-service**:

### Menggunakan NSSM (Rekomendasi):
1. Download NSSM dari [nssm.cc](https://nssm.cc/download).
2. Ekstrak `nssm.exe` ke `C:\Services\nssm.exe`.
3. Buka CMD Administrator dan jalankan:
   ```cmd
   C:\Services\nssm.exe install LocalConnectorService
   ```
4. Di jendela GUI NSSM yang muncul:
   - **Path**: `C:\Program Files\nodejs\node.exe` (Path Node.js)
   - **Startup directory**: `C:\Services\local-connector`
   - **Arguments**: `src/agent.js`
5. Klik **Install service**.
6. Jalankan service:
   ```cmd
   net start LocalConnectorService
   ```

---

## 🛡️ Aturan Firewall Windows
Jika ingin mengakses `/health` dari PC lain di LAN yang sama:
- Buka **Windows Defender Firewall** -> **Advanced Settings**.
- Tambahkan **Inbound Rule** baru:
  - Rule Type: **Port**
  - Protocol: **TCP**, Port: **8000**
  - Action: **Allow the connection**
  - Name: `Local Connector Agent (Port 8000)`

---

## 🔍 Diagnostic & Troubleshooting

| Gejala | Penyebab | Solusi |
| :--- | :--- | :--- |
| **AUTH_FAILED (401)** | Token di `.env` agent tidak cocok dengan token di Laravel | Samakan `CONNECTOR_TOKEN` di `.env` dengan token di Web App |
| **UNREACHABLE / TIMEOUT** | PC sekolah tidak bisa konek ke Internet/Domain Laravel | Cek koneksi internet PC & periksa firewall outbound |
| **DUPLICATE LOGS** | Log scan yang sama dipush berulang kali | Sistem Laravel otomatis mengabaikan log duplikat (Idempotent) |
