api-btekno/CRON_EXPLANATION.md

# Penjelasan Cron Job untuk Hourly Summary

## Konsep "Jam 2 Update Jam 1"

### Timeline Peristiwa:

```
Jam 1:00 → Event masuk ke entry_events (masih berlangsung)
Jam 1:59 → Event masih bisa masuk
Jam 2:00 → Cron job jalan → Update data untuk jam 1:00 (yang baru saja selesai)
```

### Mengapa Update Jam yang Baru Selesai?

1. **Data sudah lengkap**: Jam 1:00 sudah selesai, tidak ada event baru lagi untuk jam tersebut
2. **Dashboard realtime**: User bisa lihat data jam 1:00 yang sudah final
3. **Efisiensi**: Hanya update jam yang baru selesai, bukan semua jam

### Contoh Timeline Sehari:

```
00:00 → Cron jalan → Update jam 23:00 kemarin (atau skip jika hari baru)
01:00 → Cron jalan → Update jam 00:00 hari ini
02:00 → Cron jalan → Update jam 01:00 hari ini
03:00 → Cron jalan → Update jam 02:00 hari ini
...
23:00 → Cron jalan → Update jam 22:00 hari ini
```

## Setup Cron Job

### Opsi 1: Update Jam Tertentu Saja (Efisien - Recommended)

```cron
# Setiap jam, update jam yang baru saja selesai
# Contoh: jam 2:00 update jam 1:00, jam 3:00 update jam 2:00
0 * * * * cd /www/wwwroot/api.btekno.cloud/api && /www/server/php/83/bin/php bin/hourly_summary.php today $(date -d '1 hour ago' +\%H)
```

**Penjelasan:**
- `0 * * * *` = Setiap jam tepat (00:00, 01:00, 02:00, dst)
- `date -d '1 hour ago' +\%H` = Ambil jam yang baru saja selesai
  - Di jam 2:00 → hasilnya `1` (jam 1:00)
  - Di jam 3:00 → hasilnya `2` (jam 2:00)
- `today` = Update untuk hari ini
- Parameter `hour` = Hanya update jam tertentu (lebih cepat)

**Keuntungan:**
- ✅ Cepat (hanya proses 1 jam)
- ✅ Efisien (tidak perlu proses semua jam)
- ✅ Realtime (data ter-update setiap jam)

### Opsi 2: Update Semua Jam Hari Ini (Simple - Tidak Efisien)

```cron
# Setiap jam, update semua jam hari ini
# Ini akan rekap semua jam dari 00:00 sampai jam sekarang
0 * * * * cd /www/wwwroot/api.btekno.cloud/api && /www/server/php/83/bin/php bin/hourly_summary.php today
```

**Penjelasan:**
- Tidak ada parameter `hour`, jadi akan rekap semua jam
- Di jam 2:00 → akan rekap jam 00:00, 01:00, 02:00 (semua jam hari ini)

**Keuntungan:**
- ✅ Simple (tidak perlu hitung jam)
- ✅ Memastikan semua jam ter-update

**Kekurangan:**
- ❌ Lambat (proses semua jam setiap kali)
- ❌ Tidak efisien untuk data besar

### Opsi 3: Rekap Final Kemarin (Opsional)

```cron
# Setiap hari jam 1 pagi, rekap semua jam kemarin (untuk memastikan data lengkap)
0 1 * * * cd /www/wwwroot/api.btekno.cloud/api && /www/server/php/83/bin/php bin/hourly_summary.php yesterday
```

**Penjelasan:**
- Rekap final untuk memastikan semua jam kemarin sudah ter-rekap dengan benar
- Berguna jika ada event yang masuk terlambat atau ada masalah di cron sebelumnya

## Contoh Eksekusi

### Di Jam 2:00 Pagi:

```bash
# Command yang dijalankan:
php bin/hourly_summary.php today 1

# Artinya:
# - Update data untuk hari ini
# - Hanya jam 1:00 saja (jam yang baru saja selesai)
# - Query: WHERE DATE(event_time) = '2025-12-17' AND HOUR(event_time) = 1
```

### Di Jam 14:00 (2 Siang):

```bash
# Command yang dijalankan:
php bin/hourly_summary.php today 13

# Artinya:
# - Update data untuk hari ini
# - Hanya jam 13:00 saja (jam yang baru saja selesai)
# - Query: WHERE DATE(event_time) = '2025-12-17' AND HOUR(event_time) = 13
```

## Verifikasi Cron Berjalan

### Cek Log Cron:

```bash
# Cek log cron di aaPanel atau:
grep "hourly_summary" /var/log/cron

# Atau cek output script:
tail -f /www/wwwroot/api.btekno.cloud/api/logs/hourly_summary.log
```

### Test Manual:

```bash
# Test update jam tertentu (misalnya jam 14)
cd /www/wwwroot/api.btekno.cloud/api
php bin/hourly_summary.php today 14

# Output yang diharapkan:
# Processing hourly summary for date: 2025-12-17, hour: 14
# Success!
# Date: 2025-12-17
# Hour: 14
# Rows processed: 12
```

### Cek Data di Database:

```sql
-- Cek apakah data jam tertentu sudah ter-update
SELECT * FROM hourly_summary 
WHERE summary_date = CURDATE() 
AND summary_hour = HOUR(NOW()) - 1
ORDER BY summary_hour DESC;
```

## Troubleshooting

### Problem: Data tidak ter-update

**Cek:**
1. Apakah cron job sudah ter-setup dengan benar?
2. Apakah PHP path di cron benar?
3. Apakah script bisa dijalankan manual?
4. Cek error log cron

**Solusi:**
```bash
# Test manual dulu
cd /www/wwwroot/api.btekno.cloud/api
php bin/hourly_summary.php today 14

# Jika berhasil, cek cron syntax
crontab -l

# Test cron dengan log
0 * * * * cd /www/wwwroot/api.btekno.cloud/api && /www/server/php/83/bin/php bin/hourly_summary.php today $(date -d '1 hour ago' +\%H) >> /tmp/hourly_cron.log 2>&1
```

### Problem: Command `date -d` tidak bekerja

**Solusi:** Gunakan format yang berbeda untuk sistem yang tidak support `-d`:

```cron
# Alternatif untuk sistem yang tidak support date -d
0 * * * * cd /www/wwwroot/api.btekno.cloud/api && /www/server/php/83/bin/php bin/hourly_summary.php today $(expr $(date +\%H) - 1)
```

Atau lebih aman, buat wrapper script:

```bash
#!/bin/bash
# File: bin/hourly_summary_wrapper.sh
cd /www/wwwroot/api.btekno.cloud/api
HOUR=$(date +%H)
PREV_HOUR=$((HOUR - 1))
if [ $PREV_HOUR -lt 0 ]; then
    PREV_HOUR=23
fi
/www/server/php/83/bin/php bin/hourly_summary.php today $PREV_HOUR
```

Lalu cron:
```cron
0 * * * * /www/wwwroot/api.btekno.cloud/api/bin/hourly_summary_wrapper.sh
```

## Kesimpulan

**Rekomendasi Setup:**
- ✅ Gunakan **Opsi 1** (update jam tertentu saja) untuk efisiensi
- ✅ Tambahkan **Opsi 3** (rekap final kemarin) untuk safety
- ✅ Monitor log untuk memastikan cron berjalan dengan benar

**Timeline:**
- Setiap jam → Update jam yang baru selesai (realtime)
- Setiap hari jam 1 pagi → Rekap final kemarin (safety)