0

Ngày giờ trong front end: lịch lặp hằng tháng lệch ngày, lệch giờ khi sang giờ mùa hè

Người dùng tạo chuỗi họp "9 giờ sáng thứ Sáu tuần thứ hai mỗi tháng" trong Outlook, rồi mở add-in đặt phòng mình làm để đặt phòng cho cả chuỗi. Add-in liệt kê các buổi họp vào cùng một ngày trong tháng, tháng nào cũng vậy, trong khi thứ Sáu tuần thứ hai mỗi tháng rơi vào một ngày khác nhau. Còn với người dùng ở nơi có giờ mùa hè, qua mốc đổi giờ là giờ họp trong add-in lệch Outlook đúng một tiếng.

Trên máy mình, mọi thứ đều đúng. Mình ở Việt Nam, nơi không có giờ mùa hè, và chuỗi họp mình tự tạo để test là "ngày 9 hằng tháng". Bug này không bao giờ hiện ra trên máy dev.

Bài này kể lại hai lỗi chồng lên nhau trong cùng một đoạn code tính lịch lặp, cách sửa từng lỗi, và bộ test ngày giờ mình giờ luôn viết cho mọi chỗ đụng tới lịch.

Hai lỗi trong một hàm

Add-in tự sinh danh sách các lần họp từ quy tắc lặp mà Outlook đưa cho, rồi gửi sang form đặt phòng. Hàm sinh lịch có hai giả định sai:

Giả định sai Hậu quả Ai gặp
Lặp hằng tháng nghĩa là "ngày N của tháng" "Thứ Sáu tuần thứ hai" thành "ngày 9 mọi tháng" Mọi người dùng chuỗi lặp kiểu tương đối
Độ lệch giờ so với UTC của ngày đầu chuỗi đúng cho mọi lần lặp Sau mốc đổi giờ, mọi buổi lệch một tiếng Người dùng ở nơi có giờ mùa hè (châu Âu, Mỹ, Úc...)

Cả hai đều không làm app crash, không có lỗi trong console. Chỉ có dữ liệu sai lặng lẽ, và người phát hiện là khách hàng.

Lỗi 1: "thứ Sáu tuần thứ hai" không phải "ngày 9"

Outlook có hai kiểu lặp hằng tháng: tuyệt đối ("ngày 15 mỗi tháng") và tương đối ("thứ Sáu tuần thứ hai", "ngày làm việc cuối cùng của tháng"). Code cũ chỉ biết kiểu đầu:

// Sai: coi mọi chuỗi hằng tháng là "ngày N của tháng"
function monthlyOccurrence(first: Date, monthsLater: number): Date {
  const d = new Date(first);
  d.setMonth(d.getMonth() + monthsLater); // lần đầu là ngày 9 → tháng nào cũng ngày 9
  return d;
}

Năm 2026, thứ Sáu tuần thứ hai của tháng Một là ngày 9, tháng Hai là ngày 13, tháng Ba là ngày 13, tháng Tư là ngày 10. Không có quy luật "ngày N" nào cả. Cách đúng là tính lại cho từng tháng:

const WEEK_NUMBER = { first: 1, second: 2, third: 3, fourth: 4, last: -1 } as const;

// Ngày trong tháng của "thứ X tuần thứ n"; null nếu tháng đó không có ngày như vậy
function relativeDay(year: number, month: number, week: keyof typeof WEEK_NUMBER, weekday: number): number | null {
  const daysInMonth = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
  const matching: number[] = [];
  for (let day = 1; day <= daysInMonth; day++) {
    if (new Date(Date.UTC(year, month, day)).getUTCDay() === weekday) matching.push(day);
  }
  const n = WEEK_NUMBER[week];
  return (n === -1 ? matching[matching.length - 1] : matching[n - 1]) ?? null;
}

Ba chi tiết dễ bỏ sót:

  • "Cuối cùng" khác "thứ tư". Tháng có năm ngày thứ Sáu thì "thứ Sáu cuối cùng" là ngày thứ năm, không phải thứ tư.
  • Tính theo UTC để tránh múi giờ của máy chạy code. new Date(2026, 1, 13) tạo nửa đêm theo giờ máy, sang máy ở múi giờ khác có thể lùi sang ngày hôm trước. Ở đây chỉ cần biết thứ mấy, nên dùng Date.UTC và getUTCDay.
  • Đặt giới hạn số vòng lặp. Một quy tắc lặp không bao giờ khớp (dữ liệu lỗi, hoặc kiểu lặp chưa hỗ trợ) sẽ làm vòng while tìm lần lặp tiếp theo chạy mãi và treo tab. Code mới dừng sau tối đa 100 năm quét.

Lỗi 2: một độ lệch giờ cho cả năm

Outlook gửi kèm múi giờ của chuỗi họp: tên múi giờ kiểu Windows (GMT Standard Time) và độ lệch so với UTC tại ngày đầu tiên của chuỗi. Code cũ lấy đúng độ lệch đó trừ cho mọi lần lặp:

London, họp 9:00 thứ Sáu tuần thứ hai, chuỗi bắt đầu tháng Một (độ lệch +0)

Lần họp      Giờ London   Độ lệch thật   Code cũ tính ra UTC   UTC đúng
13/03/2026   9:00         +0 (GMT)       09:00Z                09:00Z
10/04/2026   9:00         +1 (BST)       09:00Z  ✗             08:00Z

Từ 29/3/2026, nước Anh sang giờ mùa hè, độ lệch thành +1. Buổi họp vẫn là 9 giờ sáng theo đồng hồ treo tường ở London. Nếu vẫn trừ +0 thì thời điểm UTC lệch đi một tiếng, và add-in hiển thị 10 giờ.

Cách đúng: mỗi lần lặp lấy độ lệch của chính nó, từ quy tắc múi giờ, không phải từ ngày đầu chuỗi. Trình duyệt đã có sẵn quy tắc múi giờ trong Intl, không cần thêm thư viện:

// Độ lệch (phút) của một múi giờ IANA tại một thời điểm, theo quy tắc múi giờ của trình duyệt
function offsetMinutes(timeZone: string, utcMs: number): number {
  const parts = new Intl.DateTimeFormat('en-US', {
    timeZone, hourCycle: 'h23',
    year: 'numeric', month: 'numeric', day: 'numeric',
    hour: 'numeric', minute: 'numeric', second: 'numeric',
  }).formatToParts(new Date(utcMs));
  const get = (type: string) => Number(parts.find((p) => p.type === type)?.value);
  const asUtc = Date.UTC(get('year'), get('month') - 1, get('day'), get('hour'), get('minute'), get('second'));
  return Math.round((asUtc - utcMs) / 60000);
}

// Giờ trên đồng hồ treo tường ở timeZone → thời điểm UTC thật
function wallClockToUtc(timeZone: string, y: number, m: number, d: number, hh: number, mm: number): number {
  const guess = Date.UTC(y, m, d, hh, mm);                 // tạm coi giờ địa phương là UTC
  const first = guess - offsetMinutes(timeZone, guess) * 60000;
  return guess - offsetMinutes(timeZone, first) * 60000;   // tính lại với độ lệch tại chính thời điểm đó
}

Còn một mảnh nữa: Outlook đưa tên múi giờ kiểu Windows (GMT Standard Time, SE Asia Standard Time), còn Intl cần tên IANA (Europe/London, Asia/Bangkok). Cần một bảng chuyển tên. Bảng chuẩn nằm trong dữ liệu CLDR của Unicode (file windowsZones.xml), đừng tự gõ tay vài dòng hay dùng.

Và một quy tắc an toàn mình giữ trong code: nếu không biết múi giờ, hoặc quy tắc múi giờ nói khác Outlook ngay ở ngày đầu tiên của chuỗi, thì quay về cách cũ (dùng độ lệch Outlook đưa). Một múi giờ làm lệch cả buổi họp đầu tiên chắc chắn là múi giờ sai, thà giữ hành vi cũ còn hơn làm sai thêm.

Bộ test ngày giờ nên có

Cả hai lỗi lọt qua vì test chỉ có "ngày 9 hằng tháng ở giờ Việt Nam". Giờ mỗi chỗ đụng tới lịch, mình viết đủ các ca sau:

Ca test Vì sao
Lặp tương đối: "thứ Sáu tuần thứ hai", "ngày làm việc cuối tháng" Bắt lỗi 1
Chuỗi đi qua mốc đổi giờ ở một múi giờ có giờ mùa hè (Europe/London, America/New_York) Bắt lỗi 2
Ngày 31 trong tháng chỉ có 30 ngày, ngày 29/2 năm không nhuận Lỗi tràn sang tháng sau
Giờ không tồn tại (1:30 sáng ngày đồng hồ nhảy từ 1:00 lên 2:00) Phải quyết định rõ: dời sang 2:30 hay báo lỗi
Chạy cả bộ test với múi giờ khác máy dev Lỗi do code ngầm dùng giờ của máy

Ca thứ hai viết bằng Vitest:

test('họp 9:00 giờ London vẫn là 9:00 sau khi sang giờ mùa hè', () => {
  const march = wallClockToUtc('Europe/London', 2026, 2, 13, 9, 0); // 13/3: còn GMT
  const april = wallClockToUtc('Europe/London', 2026, 3, 10, 9, 0); // 10/4: đã sang BST
  expect(new Date(march).toISOString()).toBe('2026-03-13T09:00:00.000Z');
  expect(new Date(april).toISOString()).toBe('2026-04-10T08:00:00.000Z');
});

Với ca cuối, trên CI chạy Linux chỉ cần đặt biến môi trường TZ=Europe/London cho bước test (Node đọc biến này để chọn múi giờ mặc định). Nếu code của bạn đâu đó dùng new Date(năm, tháng, ngày) mà lẽ ra phải dùng UTC, nó sẽ đỏ ngay.

Bonus: ô nhập giờ, cho gõ thay vì bắt chọn

Cùng chủ đề ngày giờ, một bài học nhỏ từ app chấm công mình làm: ô chọn giờ kiểu dropdown cuộn từng 15 phút làm người dùng phát mệt khi phải sửa hàng chục dòng chấm công. Đổi sang ô cho gõ thẳng, hiểu được nhiều kiểu gõ quen tay, và luôn dùng định dạng 24 giờ:

// "9" → "09:00", "930" → "09:30", "9:30" → "09:30", "21h" → "21:00"; null nếu không hợp lệ
function parseTime(input: string): string | null {
  const digits = input.trim().toLowerCase().replace(/[.:h]/g, '');
  if (!/^[0-9]{1,4}$/.test(digits)) return null;
  const padded = digits.length <= 2 ? digits.padStart(2, '0') + '00' : digits.padStart(4, '0');
  const hh = Number(padded.slice(0, 2));
  const mm = Number(padded.slice(2));
  if (hh > 23 || mm > 59) return null;
  return String(hh).padStart(2, '0') + ':' + String(mm).padStart(2, '0');
}

Gõ xong, rời ô thì hiện lại giá trị đã chuẩn hoá (930 thành 09:30), để người dùng thấy ngay app hiểu đúng ý họ. Dropdown vẫn giữ cho ai thích bấm, nhưng không còn là cách duy nhất.


Thử ngay: tìm trong code front end của bạn mọi chỗ có setMonth, setDate, hoặc cộng 24 * 60 * 60 * 1000 để sang ngày hôm sau. Mỗi chỗ là một ứng viên cho một trong hai lỗi ở trên. Rồi chạy bộ test với TZ=Europe/London một lần và xem có gì đỏ không.

Bài sau trong series: vì sao component không nên gọi API trực tiếp, và cách dựng một tầng dữ liệu bám theo hợp đồng API để đổi từ dữ liệu mẫu sang dữ liệu thật mà không sửa màn hình nào. Bạn từng dính bug ngày giờ nào oái oăm nhất? Comment kể mình nghe với.

P.S. Bảng "bộ test ngày giờ nên có" ở trên, mình không tự nghĩ ra hết trong một lần. Bây giờ trước khi code phần nào đụng tới lịch, mình chạy skill edge-case-scenario-gen trong PrimeKit, bộ skill mình tự làm. Skill tách tính năng ra theo 12 chiều (dữ liệu biên, thời gian, múi giờ, quyền, đồng thời...) để liệt kê các ca dễ sót trước khi viết code. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:edge-case-scenario-gen kèm mô tả tính năng. Quyết định ca nào đáng viết test vẫn là việc của bạn.


Series khác của mình


All rights reserved

Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí