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)

# 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)

# 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)

# 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:

# 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):

# 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:

# 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:

# 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:

-- 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:

# 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:

# 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:

#!/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:

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)