Lewati ke isi

Datetime and Timezone Policy

Dokumen ini adalah SSOT untuk formatting tanggal/waktu frontend dan kontrak timezone FE-BE.

Facade Wajib

  • Display tanggal/waktu user-facing wajib memakai preset dari src/utils/dateFormat.js.
  • Konversi Odoo UTC, timezone sekolah, datetime-local, date-only, dan day/month range wajib memakai src/utils/timezone.js.
  • src/utils/formatters.js hanya compatibility layer dan tidak boleh menambah logic datetime baru.

Yang Tidak Boleh

  • Jangan memakai Intl.DateTimeFormat, toLocaleDateString, atau toLocaleTimeString langsung di runtime non-util.
  • Jangan mengubah <input type="datetime-local"> ke payload Odoo dengan new Date(value).toISOString().
  • Jangan menyimpan hasil resolveSchoolTimezone() sebagai konstanta module-level di service.
  • Jangan memakai browser-local timezone untuk payload Odoo datetime.

Yang Boleh

  • Date.now() untuk timestamp teknis, ID sementara, atau pengukuran durasi.
  • toLocaleString() untuk numeric/currency formatting.
  • date-fns untuk calendar math jika tidak melakukan display atau payload timezone.
  • Intl.DateTimeFormat hanya di src/utils/timezone.js.

Pola Canonical

import { formatShortDateTime } from "@/utils/dateFormat";
import {
  datetimeLocalInputToUtcOdoo,
  formatDateTimeLocalValueInTimezone,
  resolveSchoolTimezone,
} from "@/utils/timezone";

const label = formatShortDateTime(record.start_time);

const timezone = resolveSchoolTimezone();
const inputValue = formatDateTimeLocalValueInTimezone(record.start_time, timezone);
const payloadValue = datetimeLocalInputToUtcOdoo(inputValue, timezone);

Enforcement

Jalankan guard berikut sebelum delivery:

npm run check:datetime-timezone

Guard ini juga dijalankan oleh npm run test:contract.

Backend/Odoo Contract

  • Odoo fields.Datetime tetap disimpan sebagai naive UTC, sesuai best practice Odoo.
  • Backend custom module wajib memakai scola_core.utils.datetime_utils untuk parsing UTC, timezone sekolah, date-only range, local-day range, dan serialisasi UTC.
  • Backend tidak boleh memakai hardcoded offset WIB, pytz langsung di domain module, fields.Date.today() untuk business day sekolah, atau datetime.combine(... time.min/time.max) untuk filter Datetime.
  • API yang mengirim datetime ke FE harus mengirim Odoo UTC string atau ISO UTC eksplisit; FE wajib membacanya lewat src/utils/timezone.js, bukan browser-local parser mentah.
  • Date-only business fields seperti due date, issued date, attendance date, dan actual return date tetap dikirim sebagai YYYY-MM-DD dan tidak boleh digeser oleh timezone.
  • Backend guard wajib hijau sebelum delivery:
cd /home/salfath/scola-odoo-module
python3 scripts/ci/check_datetime_timezone.py
python3 -m unittest discover -s scola_core/tests -p 'test_datetime_*_unit.py'