Add detailed explanation for hourly cron job concept (jam 2 update jam 1)

CRON_EXPLANATION.md

@@ -0,0 +1,208 @@
+# 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)
+

DEPLOYMENT.md

@@ -215,13 +215,29 @@ Setup di aaPanel → Cron:
 **Penjelasan:**
 
 1. **Daily summary**: Rekap harian untuk kemarin (jalan jam 1 pagi)
-2. **Hourly summary - REALTIME**: Update setiap jam untuk jam yang baru saja berlalu (untuk dashboard realtime)
+
-3. **Hourly summary - FINAL RECAP**: Rekap final semua jam kemarin (opsional, untuk memastikan data lengkap)
+2. **Hourly summary - REALTIME**: 
+   - **Konsep**: Setiap jam, update data untuk jam yang **baru saja selesai**
+   - **Contoh timeline**:
+     ```
+     Jam 2:00 → Cron jalan → Update jam 1:00 (yang baru selesai)
+     Jam 3:00 → Cron jalan → Update jam 2:00 (yang baru selesai)
+     Jam 14:00 → Cron jalan → Update jam 13:00 (yang baru selesai)
+     ```
+   - **Kenapa?** Karena jam yang baru selesai sudah tidak ada event baru lagi, jadi data sudah final dan bisa di-rekap
+   - **Command**: `$(date -d '1 hour ago' +\%H)` = ambil jam yang baru saja selesai
+     - Di jam 2:00 → hasilnya `1` (update jam 1:00)
+     - Di jam 14:00 → hasilnya `13` (update jam 13:00)
+
+3. **Hourly summary - FINAL RECAP**: 
+   - Rekap final semua jam kemarin (opsional, untuk memastikan data lengkap)
+   - Berguna jika ada event yang masuk terlambat atau ada masalah di cron sebelumnya
 
 **Note**: 
 - Ganti `/www/server/php/83/bin/php` dengan path PHP yang sesuai di server Anda
 - Untuk update realtime, cron harus jalan **setiap jam** (`0 * * * *`)
 - Script default ke `today` jika tidak ada argumen, jadi cocok untuk update realtime
+- Lihat `CRON_EXPLANATION.md` untuk penjelasan lengkap tentang konsep cron job
 
 ## ✅ Verification