# Timezone Configuration: UTC+8 vs Asia/Kuala_Lumpur

## Current Configuration

**Django Setting:** `TIME_ZONE = "Asia/Kuala_Lumpur"`  
**Location:** `backend/config/settings_base.py`

## Why Asia/Kuala_Lumpur Instead of UTC+8?

Django's `TIME_ZONE` setting requires an IANA timezone database name (e.g., `"Asia/Kuala_Lumpur"`), not a fixed offset string like `"UTC+8"`. While Django/pytz technically supports some offset-based timezones, using a proper IANA timezone name is the recommended approach.

## Comparison: UTC+8 Offset vs Asia/Kuala_Lumpur

### Option 1: Fixed UTC+8 Offset (Not Directly Supported)

**Pros:**
- ✅ Explicitly shows the exact offset (+08:00)
- ✅ No ambiguity about which timezone is intended
- ✅ No dependency on geographic location

**Cons:**
- ❌ **Not directly supported** by Django's `TIME_ZONE` setting
- ❌ Would require custom timezone implementation or workarounds
- ❌ Loses timezone context (no geographic meaning)
- ❌ Harder to maintain and less standard

### Option 2: Asia/Kuala_Lumpur (Current Choice)

**Pros:**
- ✅ **Directly supported** by Django (standard IANA timezone)
- ✅ Effectively UTC+8 (no DST observed)
- ✅ Provides proper timezone context for date/time operations
- ✅ Standard Django best practice
- ✅ Works seamlessly with `django.utils.timezone`
- ✅ Proper timezone-aware datetime handling
- ✅ Easy to maintain and understand

**Cons:**
- ⚠️ Uses a geographic location name (may confuse if not familiar with Malaysia timezone)
- ⚠️ If Malaysia ever changes timezone rules, it would affect the system (extremely unlikely)

## Technical Details

### How Django Handles Timezones

With `USE_TZ = True` (enabled in our settings):

1. **Database Storage:** All datetimes are stored in UTC
2. **Application Layer:** Django converts to `TIME_ZONE` (Asia/Kuala_Lumpur) when:
   - Displaying dates/times
   - Parsing user input
   - Using `timezone.now()` (returns timezone-aware datetime in Asia/Kuala_Lumpur)
   - Date comparisons and calculations

### Asia/Kuala_Lumpur Timezone Facts

- **UTC Offset:** +08:00 (UTC+8)
- **DST:** No daylight saving time observed
- **Effectively:** Same as fixed UTC+8 offset
- **IANA Name:** `Asia/Kuala_Lumpur`
- **Alternative Names:** `Asia/Singapore` (also UTC+8, no DST)

### Impact on Reward Calculation

The reward calculation command (`calculate_rewards.py`) uses:
- `timezone.now()` - Returns current time in Asia/Kuala_Lumpur (UTC+8)
- `timezone.now().date()` - Returns current date in Asia/Kuala_Lumpur (UTC+8)

This ensures:
- ✅ Calculations happen at 00:00 UTC+8 as required
- ✅ Date comparisons use UTC+8 dates
- ✅ All datetime operations respect the UTC+8 timezone

## Verification

To verify the timezone is working correctly:

```python
from django.utils import timezone
import pytz

# Check current timezone
print(timezone.get_current_timezone())  # Should show: Asia/Kuala_Lumpur

# Check UTC offset
kl_tz = pytz.timezone('Asia/Kuala_Lumpur')
now_kl = timezone.now()
print(now_kl.tzinfo)  # Should show Asia/Kuala_Lumpur
print(now_kl.utcoffset())  # Should show +08:00:00
```

## Cronjob Configuration

The cronjob script should also respect UTC+8:

```bash
# Runs at 00:00 UTC+8 (16:00 UTC)
0 16 * * * TZ=Asia/Shanghai /path/to/script.sh
```

**Note:** Using `TZ=Asia/Shanghai` in cronjob is fine (also UTC+8, no DST). The important part is that both Django and cronjob use UTC+8.

## Recommendation

**✅ Use `Asia/Kuala_Lumpur`** - It's the correct Django way to achieve UTC+8, provides proper timezone context, and works seamlessly with Django's timezone utilities.

## References

- [Django Timezone Documentation](https://docs.djangoproject.com/en/stable/topics/i18n/timezones/)
- [IANA Timezone Database](https://www.iana.org/time-zones)
- [List of UTC+8 Timezones](https://en.wikipedia.org/wiki/UTC%2B08:00)