Timezone & DateTime

Thời gian là một concern xuyên suốt mọi domain (booking, lịch học, roster, hóa đơn, gửi tin). Sai timezone là một trong những lỗi khó chịu và phổ biến nhất, nên hệ thống có quy ước rõ ràng.

Nguyên tắc nền

• Lưu thời điểm tuyệt đối ở UTC (vd AutomationScheduler.ScheduledOn là UTC).
• Hiển thị / nghiệp vụ local dựa trên timezone phù hợp (BU hoặc user) — kèm *LocalDate + TimeZoneId khi cần giữ "lịch local của BU".
• API dùng hợp đồng UTC thống nhất (timestamp truyền dạng UTC) để client/server không hiểu lệch.

Hai chế độ service area

Chế độ	Nghĩa
Local	Toàn enterprise một múi giờ.
MultiZone	Nhiều múi giờ; cần convert giữa timezone nguồn (BU) và đích (user).

Chế độ là EnterpriseSetting.ServiceAreaId (NEW, INT NOT NULL DEFAULT 0) — authoritative ở cấp enterprise. Cột BU-level cũ (BusinessUnitSetting.ServiceAreaId) còn tồn tại nhưng code mới nên bỏ qua (sẽ cleanup phase sau).

Ai sở hữu cái gì (ownership timezone)

Khái niệm	Owner	Field
Chế độ service area	EnterpriseSetting	ServiceAreaId
Timezone của user	User	User.TimezoneIdentifier (Windows TZ ID, nullable)
Timezone BU (nguồn convert ở MultiZone)	BusinessUnitSetting	TimezoneIdentifier (required)
Định dạng ngày của user	User	User.DateFormat (nullable)
Định dạng giờ của user	User	User.TimeFormat (nullable)

Công thức convert MultiZone

dayjs.tz(rawValue, buIana).tz(userIana)

Cả hai IANA id được resolve từ Windows TZ ID qua windowsToIana(). (Hệ thống lưu Windows TZ ID, convert sang IANA khi tính toán.)

Một số quy ước/cạm bẫy

Quy ước	Ghi chú
DateBased reminder	scheduledOn = local send time → UTC theo timezone BU; DST giải theo product rule.
*Date vs *DateTime	*Date chỉ ngày (không giờ → không lệ thuộc timezone); *DateTime có giờ.
*On vs *At	*On = audit/lifecycle; *At = event/integration timestamp.
Calendar/session local time	Hiển thị theo local; loại closure days trước khi preview (xem Subscription Step 1).
Booking cut-off	Lưu phút (CutOffMinute), tính theo thời điểm — cẩn trọng timezone khi so "đã quá hạn chưa".

Liên quan

• Database & lưu trữ — quy ước *Date/*DateTime/*On/*At.
• Communication → Automation — ScheduledOn UTC + local schedule.