# 📍 Panduan Location Tolerance & Validation

## 📌 Ringkasan
Aplikasi menggunakan sistem **Location Tolerance** untuk memberikan margin keamanan pada validasi lokasi absensi. Ini memastikan user yang berada di tepi area absensi tetap bisa melakukan absensi dengan baik.

---

## 🎯 Konsep Tolerance Margin

### **Radius Area Absensi**
- **Radius Utama**: 100 meter
- **Tolerance Margin**: 50 meter
- **Total Area Valid**: 100m + 50m = **150 meter**

### **Mengapa Perlu Tolerance?**
GPS pada smartphone memiliki akurasi:
- **Akurasi terbaik**: ±5 meter
- **Akurasi normal**: ±10-20 meter
- **Akurasi di area terbuka**: ±5-10 meter
- **Akurasi di area terbatas**: ±20-50 meter

Tanpa tolerance margin, user yang berada di area tepat di tepi radius bisa ditolak meskipun sebenarnya sudah di area yang benar.

---

## ⚙️ Konfigurasi

File: `config/AppConfig.kt`

```kotlin
// Lokasi Kampus
const val CAMPUS_LATITUDE = -6.8961       // Latitude kampus
const val CAMPUS_LONGITUDE = 107.6100     // Longitude kampus

// Radius Area Absensi
const val ATTENDANCE_RADIUS_METERS = 100f // Radius utama (meter)

// Tolerance Margin
const val LOCATION_TOLERANCE_MARGIN = 50f // Margin tambahan (meter)
```

### **Cara Mengubah Nilai:**

1. **Untuk menambah area valid:**
   ```kotlin
   const val LOCATION_TOLERANCE_MARGIN = 75f  // Naikkan menjadi 75 meter
   ```

2. **Untuk mengurangi area valid:**
   ```kotlin
   const val LOCATION_TOLERANCE_MARGIN = 25f  // Turunkan menjadi 25 meter
   ```

3. **Untuk ketat penuh (tanpa tolerance):**
   ```kotlin
   const val LOCATION_TOLERANCE_MARGIN = 0f   // Tolerance 0 meter
   ```

---

## 📊 Status Lokasi

Sistem membagi lokasi menjadi 3 status:

### **1. DALAM_AREA** ✓ (Status Hijau)
- **Jarak dari kampus**: ≤ 100 meter
- **Status**: "✓ Berada dalam area absensi"
- **Warna**: Hijau (#4CAF50)
- **Absensi**: ✅ **DITERIMA**

### **2. DALAM_AREA_TOLERANSI** ✓ (Status Hijau, Warning)
- **Jarak dari kampus**: 100m - 150 meter
- **Status**: "✓ Berada dalam area absensi (toleransi)"
- **Info tambahan**: "⚠️ Berada di tepi area (Xm dari batas)"
- **Warna**: Hijau (#4CAF50)
- **Absensi**: ✅ **DITERIMA** (dengan peringatan)

### **3. DI_LUAR_AREA** ✗ (Status Merah)
- **Jarak dari kampus**: > 150 meter
- **Status**: "✗ Berada di luar area absensi"
- **Warna**: Merah (#f44336)
- **Absensi**: ❌ **DITOLAK**

---

## 🔍 Tampilan Status di Aplikasi

### **AttendanceScreen (Layar Utama)**

```
┌─────────────────────────────────┐
│ 📍 Status Lokasi                │
├─────────────────────────────────┤
│ Lat: -6.8961                    │
│ Lon: 107.6100                   │
│ Jarak: 85.2m                    │
│                                 │
│ ✓ Berada dalam area absensi     │
│                                 │
│ ⚠️ Berada di tepi area (12m     │
│    dari batas)                  │
│                                 │
│ ↻ Perbarui Lokasi               │
└─────────────────────────────────┘
```

### **HistoryScreen (Riwayat)**

Setiap record menampilkan:
- 📍 Koordinat saat absensi
- 📏 Jarak dari kampus dengan status (✓ atau ✗)
- 📅 Tanggal dan waktu
- Status: Diterima/Ditolak/Pending

---

## 🛠️ Logika Validasi

### **File: `domain/usecase/LocationValidator.kt`**

```kotlin
fun isWithinRadius(
    userLatitude: Double,
    userLongitude: Double
): Boolean {
    val distance = getDistanceFromCenter(userLatitude, userLongitude)
    // Validasi dengan tolerance margin
    return distance <= (100f + 50f)  // = 150 meter
}
```

### **Contoh Perhitungan:**

1. **User di koordinat: -6.8950, 107.6090**
   - Jarak: 85 meter
   - Status: ✓ DALAM_AREA (85m ≤ 100m)
   - Absensi: **DITERIMA**

2. **User di koordinat: -6.8945, 107.6080**
   - Jarak: 125 meter
   - Status: ✓ DALAM_AREA_TOLERANSI (100m < 125m ≤ 150m)
   - Absensi: **DITERIMA** (dengan warning)

3. **User di koordinat: -6.8930, 107.6060**
   - Jarak: 160 meter
   - Status: ✗ DI_LUAR_AREA (160m > 150m)
   - Absensi: **DITOLAK**

---

## 🔧 Tips Troubleshooting

### **1. Lokasi Tidak Terdeteksi**
- ✅ Pastikan GPS device aktif
- ✅ Pastikan izin lokasi diberikan
- ✅ Tunggu beberapa detik (GPS butuh waktu untuk akurat)
- ✅ Keluar dari ruangan jika memungkinkan
- ✅ Klik "Perbarui Lokasi" beberapa kali

### **2. Ditolak Padahal Seharusnya Diterima**
- ✅ Toleransi margin: Increase LOCATION_TOLERANCE_MARGIN
- ✅ Cek GPS accuracy: Biasanya ±10-20 meter
- ✅ Pindah sedikit ke arah kampus
- ✅ Tunggu GPS stabil sebelum absen

### **3. Terlalu Ketat**
- ✅ Decrease ATTENDANCE_RADIUS_METERS jika area terlalu luas
- ✅ Decrease LOCATION_TOLERANCE_MARGIN jika ingin lebih ketat

---

## 📈 Rekomendasi Pengaturan

### **Untuk Area Terbuka (Outdoor)**
```kotlin
const val ATTENDANCE_RADIUS_METERS = 100f
const val LOCATION_TOLERANCE_MARGIN = 30f  // GPS akurat ±5-10m
```

### **Untuk Area Standar (Kampus)**
```kotlin
const val ATTENDANCE_RADIUS_METERS = 100f
const val LOCATION_TOLERANCE_MARGIN = 50f  // GPS standar ±15-20m
```

### **Untuk Area Terbatas (Indoor/Urban)**
```kotlin
const val ATTENDANCE_RADIUS_METERS = 100f
const val LOCATION_TOLERANCE_MARGIN = 75f  // GPS kurang akurat ±30-50m
```

### **Untuk Keamanan Maksimal (Ketat)**
```kotlin
const val ATTENDANCE_RADIUS_METERS = 100f
const val LOCATION_TOLERANCE_MARGIN = 0f   // Tanpa margin
```

---

## 🔐 Server-Side Validation

Meskipun aplikasi sudah memberikan tolerance, server (N8n) juga melakukan validasi:

1. **Menerima data lokasi dari aplikasi**
2. **Validasi ulang dengan radius dari server**
3. **Update status absensi** (accepted/rejected)
4. **Simpan log** untuk audit trail

---

## 📝 Perubahan di Versi 1.1

- ✅ Menambahkan tolerance margin untuk GPS accuracy
- ✅ Menambahkan status detail lokasi (DALAM_AREA_TOLERANSI)
- ✅ Menampilkan warning saat berada di tepi area
- ✅ Membuat margin dapat dikonfigurasi di AppConfig
- ✅ Menambahkan perhitungan jarak detail di HistoryScreen

---

## 📞 Support

Jika ada pertanyaan atau masalah dengan validasi lokasi:
1. Cek GPS status device
2. Cek konfigurasi di `config/AppConfig.kt`
3. Lihat logika di `domain/usecase/LocationValidator.kt`
4. Pantau server logs di N8n dashboard

---

**Last Updated**: 14 Januari 2026  
**Version**: 1.1.0