First commit

backend/internal/pkg/timezone/timezone.go

@@ -0,0 +1,124 @@
+// Package timezone provides global timezone management for the application.
+// Similar to PHP's date_default_timezone_set, this package allows setting
+// a global timezone that affects all time.Now() calls.
+package timezone
+
+import (
+	"fmt"
+	"log"
+	"time"
+)
+
+var (
+	// location is the global timezone location
+	location *time.Location
+	// tzName stores the timezone name for logging/debugging
+	tzName string
+)
+
+// Init initializes the global timezone setting.
+// This should be called once at application startup.
+// Example timezone values: "Asia/Shanghai", "America/New_York", "UTC"
+func Init(tz string) error {
+	if tz == "" {
+		tz = "Asia/Shanghai" // Default timezone
+	}
+
+	loc, err := time.LoadLocation(tz)
+	if err != nil {
+		return fmt.Errorf("invalid timezone %q: %w", tz, err)
+	}
+
+	// Set the global Go time.Local to our timezone
+	// This affects time.Now() throughout the application
+	time.Local = loc
+	location = loc
+	tzName = tz
+
+	log.Printf("Timezone initialized: %s (UTC offset: %s)", tz, getUTCOffset(loc))
+	return nil
+}
+
+// getUTCOffset returns the current UTC offset for a location
+func getUTCOffset(loc *time.Location) string {
+	_, offset := time.Now().In(loc).Zone()
+	hours := offset / 3600
+	minutes := (offset % 3600) / 60
+	if minutes < 0 {
+		minutes = -minutes
+	}
+	sign := "+"
+	if hours < 0 {
+		sign = "-"
+		hours = -hours
+	}
+	return fmt.Sprintf("%s%02d:%02d", sign, hours, minutes)
+}
+
+// Now returns the current time in the configured timezone.
+// This is equivalent to time.Now() after Init() is called,
+// but provided for explicit timezone-aware code.
+func Now() time.Time {
+	if location == nil {
+		return time.Now()
+	}
+	return time.Now().In(location)
+}
+
+// Location returns the configured timezone location.
+func Location() *time.Location {
+	if location == nil {
+		return time.Local
+	}
+	return location
+}
+
+// Name returns the configured timezone name.
+func Name() string {
+	if tzName == "" {
+		return "Local"
+	}
+	return tzName
+}
+
+// StartOfDay returns the start of the given day (00:00:00) in the configured timezone.
+func StartOfDay(t time.Time) time.Time {
+	loc := Location()
+	t = t.In(loc)
+	return time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, loc)
+}
+
+// Today returns the start of today (00:00:00) in the configured timezone.
+func Today() time.Time {
+	return StartOfDay(Now())
+}
+
+// EndOfDay returns the end of the given day (23:59:59.999999999) in the configured timezone.
+func EndOfDay(t time.Time) time.Time {
+	loc := Location()
+	t = t.In(loc)
+	return time.Date(t.Year(), t.Month(), t.Day(), 23, 59, 59, 999999999, loc)
+}
+
+// StartOfWeek returns the start of the week (Monday 00:00:00) for the given time.
+func StartOfWeek(t time.Time) time.Time {
+	loc := Location()
+	t = t.In(loc)
+	weekday := int(t.Weekday())
+	if weekday == 0 {
+		weekday = 7 // Sunday is day 7
+	}
+	return time.Date(t.Year(), t.Month(), t.Day()-weekday+1, 0, 0, 0, 0, loc)
+}
+
+// StartOfMonth returns the start of the month (1st day 00:00:00) for the given time.
+func StartOfMonth(t time.Time) time.Time {
+	loc := Location()
+	t = t.In(loc)
+	return time.Date(t.Year(), t.Month(), 1, 0, 0, 0, 0, loc)
+}
+
+// ParseInLocation parses a time string in the configured timezone.
+func ParseInLocation(layout, value string) (time.Time, error) {
+	return time.ParseInLocation(layout, value, Location())
+}

backend/internal/pkg/timezone/timezone_test.go

@@ -0,0 +1,127 @@
+package timezone
+
+import (
+	"testing"
+	"time"
+)
+
+func TestInit(t *testing.T) {
+	// Test with valid timezone
+	err := Init("Asia/Shanghai")
+	if err != nil {
+		t.Fatalf("Init failed with valid timezone: %v", err)
+	}
+
+	// Verify time.Local was set
+	if time.Local.String() != "Asia/Shanghai" {
+		t.Errorf("time.Local not set correctly, got %s", time.Local.String())
+	}
+
+	// Verify our location variable
+	if Location().String() != "Asia/Shanghai" {
+		t.Errorf("Location() not set correctly, got %s", Location().String())
+	}
+
+	// Test Name()
+	if Name() != "Asia/Shanghai" {
+		t.Errorf("Name() not set correctly, got %s", Name())
+	}
+}
+
+func TestInitInvalidTimezone(t *testing.T) {
+	err := Init("Invalid/Timezone")
+	if err == nil {
+		t.Error("Init should fail with invalid timezone")
+	}
+}
+
+func TestTimeNowAffected(t *testing.T) {
+	// Reset to UTC first
+	Init("UTC")
+	utcNow := time.Now()
+
+	// Switch to Shanghai (UTC+8)
+	Init("Asia/Shanghai")
+	shanghaiNow := time.Now()
+
+	// The times should be the same instant, but different timezone representation
+	// Shanghai should be 8 hours ahead in display
+	_, utcOffset := utcNow.Zone()
+	_, shanghaiOffset := shanghaiNow.Zone()
+
+	expectedDiff := 8 * 3600 // 8 hours in seconds
+	actualDiff := shanghaiOffset - utcOffset
+
+	if actualDiff != expectedDiff {
+		t.Errorf("Timezone offset difference incorrect: expected %d, got %d", expectedDiff, actualDiff)
+	}
+}
+
+func TestToday(t *testing.T) {
+	Init("Asia/Shanghai")
+
+	today := Today()
+	now := Now()
+
+	// Today should be at 00:00:00
+	if today.Hour() != 0 || today.Minute() != 0 || today.Second() != 0 {
+		t.Errorf("Today() not at start of day: %v", today)
+	}
+
+	// Today should be same date as now
+	if today.Year() != now.Year() || today.Month() != now.Month() || today.Day() != now.Day() {
+		t.Errorf("Today() date mismatch: today=%v, now=%v", today, now)
+	}
+}
+
+func TestStartOfDay(t *testing.T) {
+	Init("Asia/Shanghai")
+
+	// Create a time at 15:30:45
+	testTime := time.Date(2024, 6, 15, 15, 30, 45, 123456789, Location())
+	startOfDay := StartOfDay(testTime)
+
+	expected := time.Date(2024, 6, 15, 0, 0, 0, 0, Location())
+	if !startOfDay.Equal(expected) {
+		t.Errorf("StartOfDay incorrect: expected %v, got %v", expected, startOfDay)
+	}
+}
+
+func TestTruncateVsStartOfDay(t *testing.T) {
+	// This test demonstrates why Truncate(24*time.Hour) can be problematic
+	// and why StartOfDay is more reliable for timezone-aware code
+
+	Init("Asia/Shanghai")
+
+	now := Now()
+
+	// Truncate operates on UTC, not local time
+	truncated := now.Truncate(24 * time.Hour)
+
+	// StartOfDay operates on local time
+	startOfDay := StartOfDay(now)
+
+	// These will likely be different for non-UTC timezones
+	t.Logf("Now: %v", now)
+	t.Logf("Truncate(24h): %v", truncated)
+	t.Logf("StartOfDay: %v", startOfDay)
+
+	// The truncated time may not be at local midnight
+	// StartOfDay is always at local midnight
+	if startOfDay.Hour() != 0 {
+		t.Errorf("StartOfDay should be at hour 0, got %d", startOfDay.Hour())
+	}
+}
+
+func TestDSTAwareness(t *testing.T) {
+	// Test with a timezone that has DST (America/New_York)
+	err := Init("America/New_York")
+	if err != nil {
+		t.Skipf("America/New_York timezone not available: %v", err)
+	}
+
+	// Just verify it doesn't crash
+	_ = Today()
+	_ = Now()
+	_ = StartOfDay(Now())
+}