Bug daylight saving time: aturan untuk timestamp dan laporan

Mengapa bug ini terjadi pada produk biasa

Bug waktu muncul di produk biasa karena orang tidak hidup dalam UTC. Mereka hidup dalam waktu lokal, dan waktu lokal bisa maju, mundur, atau berubah aturannya selama bertahun-tahun. Dua pengguna bisa melihat momen yang sama dan melihat jam yang berbeda. Lebih parah lagi, jam lokal yang sama bisa merujuk ke dua momen nyata yang berbeda.

Bug daylight saving time (DST) sering muncul hanya dua kali setahun, jadi mudah terlewat. Semua terlihat normal saat pengembangan, lalu seorang pelanggan nyata menjadwalkan janji, mengisi timesheet, atau memeriksa laporan pada akhir pekan perpindahan dan sesuatu terasa tidak benar.

Tim biasanya melihat beberapa pola: “jam yang hilang” di mana item terjadwal hilang atau bergeser, jam terduplikasi di mana log atau alert tampak ganda, dan total harian yang menggeser karena satu “hari” jadi 23 atau 25 jam.

Ini bukan hanya masalah developer. Support mendapat tiket seperti “aplikasi Anda mengubah waktu rapat saya.” Keuangan melihat pendapatan harian yang tidak cocok. Operasi bertanya-tanya mengapa job semalaman berjalan dua kali atau terlewat. Bahkan filter “dibuat hari ini” bisa berbeda antar pengguna di region berbeda.

Tujuannya membosankan dan dapat diandalkan: simpan waktu dengan cara yang tidak kehilangan makna, tampilkan waktu lokal seperti yang diharapkan manusia, dan bangun laporan yang tetap benar bahkan di hari-hari aneh. Saat Anda melakukan itu, semua bagian bisnis bisa mempercayai angkanya.

Baik Anda membangun dengan kode kustom atau platform seperti AppMaster, aturannya sama. Anda ingin timestamp yang menjaga momen asli, plus konteks yang cukup (seperti zona waktu pengguna) untuk menjelaskan seperti apa momen itu di jam mereka.

Model waktu singkat dengan bahasa sederhana

Sebagian besar bug DST terjadi karena kita mencampur "sebuah momen di waktu" dengan "bagaimana jam menampilkannya." Pisahkan ide-ide itu dan aturannya jadi jauh lebih sederhana.

Beberapa istilah, dalam bahasa sederhana:

• Timestamp: sebuah momen tepat di garis waktu (tidak tergantung lokasi).
• UTC: jam acuan global untuk merepresentasikan timestamp secara konsisten.
• Waktu lokal: apa yang dilihat orang di jam dinding di suatu tempat (misal 9:00 AM di New York).
• Offset: selisih dari UTC pada momen tertentu, dituliskan seperti +02:00 atau -05:00.
• Zona waktu: nama yang membawa sekumpulan aturan yang menentukan offset untuk setiap tanggal, seperti America/New_York.

Offset bukan sama dengan zona waktu. -05:00 hanya memberi tahu selisih dari UTC pada satu momen. Itu tidak menjelaskan apakah tempat itu beralih ke -04:00 saat musim panas, atau jika hukum berubah tahun depan. Nama zona waktu melakukannya, karena membawa aturan dan sejarah.

DST mengubah offset, bukan timestamp mendasar. Kejadian tetap terjadi pada momen yang sama; hanya label jam lokal yang berubah.

Dua situasi menyebabkan kebingungan paling sering:

• Loncat musim semi: jam melompat maju, jadi rentang waktu lokal tidak pernah ada (misalnya 2:30 AM bisa tidak mungkin).
• Ulang musim gugur: jam terulang satu jam, jadi waktu lokal yang sama terjadi dua kali (misalnya 1:30 AM bisa ambigu).

Jika tiket support dibuat pada “1:30 AM” selama pengulangan musim gugur, Anda perlu zona waktu dan momen tepat (timestamp UTC) untuk mengurutkan event dengan benar.

Aturan data yang mencegah sebagian besar masalah

Sebagian besar bug DST bermula sebagai masalah data, bukan sekadar format. Jika nilai yang disimpan tidak jelas, setiap layar dan laporan nanti harus menebak, dan tebakan-tebakan itu akan berbeda.

Aturan 1: Simpan kejadian nyata sebagai momen absolut (UTC)

Jika sesuatu terjadi pada momen tertentu (pembayaran diterima, tiket dibalas, shift dimulai), simpan timestamp dalam UTC. UTC tidak melompat maju atau mundur, jadi tetap stabil saat perubahan DST.

Contoh: Seorang agen support di New York membalas pada 9:15 AM waktu lokal pada hari perubahan jam. Menyimpan momen UTC menjaga balasan itu tetap berurutan saat seseorang di London meninjau thread nanti.

Aturan 2: Simpan konteks zona waktu sebagai ID zona waktu IANA

Saat Anda perlu menampilkan waktu secara manusiawi, Anda perlu tahu zona waktu pengguna atau lokasi. Simpan sebagai ID zona waktu IANA seperti America/New_York atau Europe/London, bukan label samar seperti “EST.” Singkatan bisa berarti hal berbeda, dan offset saja tidak menangkap aturan DST.

Polanya sederhana: waktu kejadian dalam UTC, ditambah ID zona waktu terpisah yang terkait dengan pengguna, kantor, toko, atau perangkat.

Aturan 3: Simpan nilai hanya-tanggal sebagai tanggal, bukan timestamp

Beberapa nilai bukan momen di waktu. Ulang tahun, “perpanjangan pada tanggal 5,” dan “jatuh tempo faktur” sering kali harus disimpan sebagai field hanya-tanggal. Jika Anda menyimpannya sebagai timestamp, konversi zona waktu bisa memindahkannya ke hari sebelumnya atau berikutnya.

Aturan 4: Jangan pernah menyimpan waktu lokal sebagai string biasa tanpa konteks zona

Hindari menyimpan nilai seperti “2026-03-08 02:30” atau “9:00 AM” tanpa zona waktu. Waktu itu bisa ambigu (terjadi dua kali) atau tidak mungkin (terlewat) selama transisi DST.

Jika Anda harus menerima input lokal, simpan nilai lokal dan ID zona waktu, lalu konversi ke UTC untuk momen kejadian yang sebenarnya.

Memutuskan apa yang disimpan untuk tiap jenis record

Banyak bug DST terjadi karena satu tipe record diperlakukan seperti tipe lain. Log audit, rapat kalender, dan cutoff payroll semua tampak seperti “tanggal dan waktu,” tapi mereka butuh data berbeda agar tetap akurat.

Untuk event masa lalu (yang sudah terjadi): simpan momen tepat, biasanya timestamp UTC. Jika Anda perlu menjelaskannya seperti yang dilihat pengguna, juga simpan zona waktu pengguna pada saat peristiwa (ID IANA seperti America/New_York, bukan hanya “EST”). Itu memungkinkan Anda membangun ulang apa yang ditampilkan layar meskipun pengguna kemudian mengubah zona waktu profilnya.

Untuk penjadwalan (yang harus terjadi pada waktu jam dinding lokal): simpan tanggal dan jam lokal yang dimaksud plus ID zona waktu. Jangan konversi ke UTC lalu buang nilai aslinya. “10 Maret jam 09:00 di Europe/Berlin” adalah niat. UTC adalah nilai turunan yang bisa berubah saat aturan berubah.

Perubahan itu normal: orang bepergian, kantor pindah, kebijakan perusahaan diubah. Untuk catatan historis, jangan tulis ulang waktu masa lalu saat pengguna mengubah zona waktu profilnya. Untuk jadwal masa depan, tentukan apakah jadwal mengikuti pengguna (travel-friendly) atau mengikuti lokasi tetap (office-friendly), dan simpan zona lokasi itu.

Data lama yang hanya punya timestamp lokal rumit. Jika Anda tahu zona sumber, lampirkan dan perlakukan waktu lama itu sebagai lokal. Jika tidak tahu, tandai sebagai “floating” dan jujur di laporan (misalnya tampilkan nilai yang disimpan tanpa konversi). Juga membantu untuk memodelkan ini sebagai field terpisah agar layar dan laporan tidak mencampur-adukkan.

Langkah demi langkah: menyimpan timestamp dengan aman

Untuk menghentikan bug DST, pilih satu sistem catatan waktu yang tidak ambigu, lalu hanya konversi saat menampilkannya ke orang.

Tuliskan aturan untuk tim Anda: semua timestamp di basis data adalah UTC. Masukkan ini di dokumentasi dan komentar kode dekat bagian penanganan tanggal. Keputusan seperti ini sering tidak sengaja dibatalkan nanti.

Pola penyimpanan praktis tampak seperti ini:

• Pilih UTC sebagai sistem catatan dan beri nama field agar jelas (misal created_at_utc).
• Tambahkan field yang benar-benar diperlukan: waktu event dalam UTC (misal occurred_at_utc), dan tz_id ketika konteks lokal penting (pakai ID zona waktu IANA seperti America/New_York, bukan offset tetap).
• Saat menerima input, kumpulkan tanggal dan waktu lokal plus tz_id, lalu konversi ke UTC satu kali di boundary (API atau submit form). Jangan konversi berulang-ulang di berbagai lapisan.
• Simpan dan query dalam UTC. Konversi ke waktu lokal hanya di tepi sistem (UI, email, export).
• Untuk tindakan berisiko tinggi (pembayaran, kepatuhan, penjadwalan), juga catat apa yang Anda terima (string lokal asli, tz_id, dan UTC yang dihitung). Ini memberi jejak audit saat pengguna mempersoalkan waktu.

Contoh: seorang pengguna menjadwalkan “5 Nov, 9:00 AM” di America/Los_Angeles. Anda menyimpan occurred_at_utc = 2026-11-05T17:00:00Z dan tz_id = America/Los_Angeles. Bahkan jika aturan DST berubah nanti, Anda tetap bisa menjelaskan apa yang mereka maksud dan apa yang disimpan.

Jika Anda memodelkannya di PostgreSQL (termasuk lewat alat pemodelan data visual), jadikan tipe kolom eksplisit dan konsisten, dan pastikan aplikasi menulis UTC setiap kali.

Menampilkan waktu lokal yang dipahami pengguna

Sebagian besar bug DST muncul di UI, bukan di database. Orang membaca apa yang Anda tunjukkan, menyalinnya ke pesan, dan merencanakannya. Jika layar tidak jelas, pengguna akan berasumsi yang salah.

Saat waktu penting (booking, tiket, janji, jendela pengiriman), tampilkan seperti struk: lengkap, spesifik, dan diberi label.

Buat tampilan yang dapat diprediksi:

• Tampilkan tanggal + waktu + zona waktu (contoh: “10 Mar 2026, 9:30 AM America/New_York”).
• Letakkan label zona waktu dekat waktu, jangan disembunyikan di pengaturan.
• Jika menampilkan teks relatif (“dalam 2 jam”), letakkan timestamp tepatnya di dekatnya.
• Untuk item bersama, pertimbangkan menampilkan waktu lokal viewer dan juga zona waktu event.

Kasus tepi DST perlu perilaku eksplisit. Jika Anda membiarkan pengguna mengetik waktu apa saja, Anda akhirnya akan menerima waktu yang tak pernah terjadi atau terjadi dua kali.

• Loncat-musim semi (waktu hilang): blokir pilihan tidak valid dan tawarkan waktu valid berikutnya.
• Ulang-musim gugur (waktu ambigu): tampilkan offset atau pilihan jelas (misal, “1:30 AM UTC-4” vs “1:30 AM UTC-5”).
• Mengedit record yang ada: pertahankan momen asli meski format berubah.

Contoh: Seorang agen support di Berlin menjadwalkan panggilan dengan pelanggan di New York untuk “3 Nov, 1:30 AM.” Saat fall-back, waktu itu terjadi dua kali di New York. Jika UI menampilkan “3 Nov, 1:30 AM (UTC-4)”, kebingungan hilang.

Membangun laporan yang tidak berbohong

Laporan merusak kepercayaan ketika data yang sama memberi total berbeda tergantung di mana viewer duduk. Untuk menghindari bug DST, putuskan apa yang sebenarnya dikelompokkan laporan, lalu patuhi itu.

Pertama, pilih makna “hari” untuk setiap laporan. Tim support sering berpikir dalam hari lokal pelanggan. Keuangan sering butuh zona waktu legal akun. Beberapa laporan teknis paling aman dalam hari UTC.

Mengelompokkan berdasarkan hari lokal mengubah total di sekitar DST. Pada hari loncat-musim semi, satu jam lokal terlewat. Pada hari ulang-musim gugur, satu jam lokal terulang. Jika Anda mengelompokkan event berdasarkan “tanggal lokal” tanpa aturan jelas, jam sibuk bisa terlihat hilang, terduplikasi, atau pindah ke hari yang salah.

Aturan praktis: setiap laporan punya satu zona waktu pelaporan, dan zona itu terlihat di header (misal, “Semua tanggal ditampilkan dalam America/New_York”). Itu membuat perhitungan dapat diprediksi dan memberi support sesuatu yang jelas untuk dirujuk.

Untuk tim multi-region, membiarkan orang mengganti zona laporan boleh saja, tapi perlakukan itu sebagai pandangan berbeda dari kebenaran yang sama. Dua viewer mungkin melihat bucket harian yang berbeda di dekat tengah malam dan transisi DST. Itu normal asalkan laporan jelas menyatakan zona yang dipilih.

Beberapa pilihan yang mencegah kejutan:

• Definisikan batas hari laporan (zona pengguna, zona akun, atau UTC) dan dokumentasikan.
• Gunakan satu zona waktu per run laporan, dan tampilkan itu di samping rentang tanggal.
• Untuk total harian, kelompokkan berdasarkan tanggal lokal di zona yang dipilih (bukan berdasarkan tanggal UTC).
• Untuk grafik per jam, beri label jam yang berulang pada hari fall-back.
• Untuk durasi, simpan dan jumlahkan detik yang berlalu, lalu format untuk tampilan.

Durasi butuh perhatian khusus. “Shift 2 jam” yang melewati fall-back adalah 3 jam jam-dinding tapi tetap 2 jam waktu berlalu jika orang benar-benar bekerja 2 jam. Tentukan makna yang diharapkan pengguna Anda, lalu terapkan pembulatan konsisten (misal, bulatkan setelah dijumlahkan, bukan per baris).

Perangkap umum dan cara menghindarinya

Bug DST bukan soal “matematika sulit.” Mereka muncul dari asumsi kecil yang merayap seiring waktu.

Kegagalan klasik adalah menyimpan timestamp lokal tetapi melabelinya sebagai UTC. Semua terlihat baik sampai seseorang di zona lain membuka record dan nilainya bergeser diam-diam. Aturan yang lebih aman sederhana: simpan instant (UTC) plus konteks yang tepat (zona pengguna atau lokasi) ketika record membutuhkan arti lokal.

Sumber sering lain adalah menggunakan offset tetap seperti -05:00. Offset tidak tahu tentang perubahan DST atau aturan historis. Gunakan ID zona IANA nyata (seperti America/New_York) agar sistem dapat menerapkan aturan yang benar untuk tanggal tersebut.

Beberapa kebiasaan mencegah banyak kejutan “double-shift”:

• Konversi hanya di tepi sistem: parse input sekali, simpan sekali, tampilkan sekali.
• Jaga garis yang jelas antara field “instant” (UTC) dan field “jam-dinding” (tanggal/waktu lokal).
• Simpan ID zona waktu di samping record yang tergantung interpretasi lokal.
• Buat zona waktu server tidak relevan dengan selalu membaca dan menulis UTC.
• Untuk laporan, tentukan zona laporan dan tampilkan di UI.

Perhatikan juga konversi tersembunyi. Pola umum: parse waktu lokal pengguna ke UTC, lalu suatu library UI mengira nilai itu lokal dan mengonversinya lagi. Hasilnya adalah pergeseran satu jam yang muncul hanya untuk beberapa pengguna dan beberapa tanggal.

Terakhir, jangan gunakan zona waktu perangkat klien untuk billing atau kepatuhan. Ponsel pelancong bisa berganti zona di perjalanan. Sebagai gantinya, dasarkan laporan pada aturan bisnis eksplisit, seperti zona akun pelanggan atau lokasi situs.

Pengujian: kasus kecil yang menemukan sebagian besar bug

Sebagian besar bug waktu muncul hanya beberapa hari dalam setahun, itulah sebabnya mereka lolos QA. Perbaikannya adalah menguji momen yang tepat dan membuat tes itu dapat diulang.

Pilih satu zona waktu yang mengamati DST (misal America/New_York atau Europe/Berlin) dan tulis tes untuk dua hari transisi. Lalu pilih satu zona yang tidak menggunakan DST (misal Asia/Singapore atau Africa/Nairobi) sehingga Anda bisa melihat perbedaan dengan jelas.

5 tes yang layak dipertahankan selamanya

• Hari spring-forward: verifikasi jam yang hilang tidak bisa dijadwalkan, dan konversi tidak menemukan waktu yang tidak pernah ada.
• Hari fall-back: verifikasi jam yang berulang, di mana dua momen UTC berbeda tampil sebagai waktu lokal yang sama. Pastikan log dan export bisa membedakannya.
• Melintasi tengah malam: buat event yang melintasi tengah malam dalam waktu lokal, dan konfirmasi pengurutan serta pengelompokan tetap benar saat dilihat dalam UTC.
• Kontras non-DST: ulangi konversi di zona tanpa DST dan pastikan hasil tetap stabil pada tanggal yang sama.
• Snapshot pelaporan: simpan total yang diharapkan untuk laporan di sekitar akhir bulan plus akhir pekan DST, dan bandingkan output setelah setiap perubahan.

Skenario konkret

Bayangkan tim support menjadwalkan tindak lanjut “01:30” pada malam fall-back. Jika UI Anda hanya menyimpan waktu lokal yang ditampilkan, Anda tidak bisa tahu "01:30" yang mana yang mereka maksud. Tes yang baik membuat kedua timestamp UTC yang memetakan ke 01:30 secara lokal dan memastikan aplikasi menyimpannya berbeda.

Tes-tes ini cepat menunjukkan apakah sistem Anda menyimpan fakta yang benar (instant UTC, ID zona waktu, dan kadang waktu lokal asli) dan apakah laporan tetap jujur saat jam berubah.

Daftar periksa cepat sebelum rilis

Bug DST lolos karena aplikasi tampak benar sebagian besar hari. Gunakan daftar periksa ini sebelum merilis apa pun yang menampilkan waktu, memfilter berdasarkan tanggal, atau mengekspor laporan.

• Pilih satu zona waktu pelaporan untuk tiap laporan (misal, “Waktu Kantor Pusat Bisnis” atau “Waktu Pengguna”). Tampilkan di header laporan dan jaga konsistensi di tabel, total, dan grafik.
• Simpan setiap “momen di waktu” sebagai UTC (created_at, paid_at, message_sent_at). Simpan ID zona IANA saat Anda butuh konteks.
• Jangan hitung dengan offset tetap seperti “UTC-5” jika DST bisa berlaku. Konversi menggunakan aturan zona waktu untuk tanggal tersebut.
• Beri label waktu dengan jelas di mana pun (UI, email, export). Sertakan tanggal, waktu, dan zona agar screenshot dan CSV tidak salah baca.
• Pertahankan set kecil tes DST: satu timestamp tepat sebelum loncat musim semi, satu tepat setelah, dan yang sama di sekitar jam pengulangan musim gugur.

Cek realitas: jika manajer support di New York mengekspor “Tiket dibuat pada hari Minggu” dan rekan di London membuka file, keduanya harus bisa tahu zona waktu apa yang direpresentasikan timestamp tanpa menebak.

Contoh: alur kerja support nyata lintas zona waktu

Seorang pelanggan di New York membuka tiket support pada minggu ketika AS sudah beralih ke daylight saving time, tetapi Inggris belum. Tim support Anda berada di London.

Pada 12 Maret, pelanggan mengirim tiket pada 09:30 waktu lokal New York. Momen itu adalah 13:30 UTC, karena New York sekarang UTC-4. Agen di London membalas pada 14:10 waktu London, yang adalah 14:10 UTC (London masih UTC+0 minggu itu). Balasan datang 40 menit setelah tiket dibuat.

Begini jika Anda hanya menyimpan waktu lokal tanpa ID zona:

• Anda menyimpan “09:30” dan “14:10” sebagai timestamp biasa.
• Job laporan kemudian mengasumsikan “New York selalu UTC-5” (atau menggunakan zona server).
• Ia mengonversi 09:30 sebagai 14:30 UTC, bukan 13:30 UTC.
• Jam SLA Anda meleset 1 jam, dan tiket yang memenuhi SLA 2 jam bisa ditandai terlambat.

Model yang lebih aman menjaga konsistensi UI dan pelaporan. Simpan waktu event sebagai timestamp UTC, dan simpan ID zona IANA yang relevan (misal America/New_York untuk pelanggan, Europe/London untuk agen). Di UI, tampilkan momen UTC yang sama dalam zona viewer menggunakan aturan yang tersimpan untuk tanggal itu.

Untuk laporan mingguan, pilih aturan jelas seperti “kelompokkan berdasarkan hari lokal pelanggan.” Hitung batas hari dalam America/New_York (dari tengah malam ke tengah malam), konversi batas-batas itu ke UTC, lalu hitung tiket di dalamnya. Angkanya tetap stabil, bahkan pada minggu DST.

Langkah berikutnya: buat penanganan waktu konsisten di seluruh aplikasi

Jika produk Anda pernah terkena bug DST, cara tercepat keluar adalah menulis beberapa aturan dan menerapkannya di mana-mana. “Hampir konsisten” adalah tempat masalah waktu bersemayam.

Jaga aturan singkat dan spesifik:

• Format penyimpanan: apa yang Anda simpan (biasanya instant dalam UTC) dan apa yang tidak Anda simpan (waktu lokal ambigu tanpa zona).
• Zona laporan: zona mana yang dipakai laporan secara default, dan bagaimana pengguna bisa mengubahnya.
• Label UI: apa yang muncul di samping waktu (misal, “10 Mar, 09:00 (America/New_York)” vs hanya “09:00”).
• Aturan pembulatan: bagaimana Anda mengelompokkan waktu (jam, hari, minggu) dan zona mana yang diikuti bucket tersebut.
• Field audit: timestamp mana yang berarti “event terjadi” vs “record dibuat/diperbarui.”

Roll-out secara bertahap. Perbaiki record baru dulu agar masalah tidak terus bertambah. Lalu migrasikan data historis secara batch. Saat migrasi, simpan kedua nilai (jika tersedia) — nilai asli dan nilai ternormalisasi — cukup lama untuk melihat perbedaan di laporan.

Jika Anda pakai AppMaster (appmaster.io), satu manfaat praktis adalah memusatkan aturan ini di model data dan business logic bersama: simpan timestamp UTC secara konsisten, pertahankan ID zona IANA di samping record yang butuh arti lokal, dan terapkan konversi di boundary input dan tampilan.

Langkah praktis selanjutnya adalah membangun satu laporan aman-zona waktu (misal “tiket terselesaikan per hari”) dan validasi menggunakan test case di atas. Jika tetap benar melintasi minggu transisi DST untuk dua zona berbeda, Anda berada di jalur yang baik.