# 🗓️ Holiday Management System - Complete Guide

## Overview
Complete admin panel for managing school holidays with automatic integration into employee attendance records.

## Features
✅ Add/Edit/Delete holidays  
✅ Bulk import holidays from JSON  
✅ Apply holidays to: Students, Staff, or Both  
✅ Automatic attendance status calculation  
✅ Pre-loaded Bangladesh national holidays  

---

## 🚀 Quick Start

### 1. Migration
```bash
php artisan migrate
```

### 2. Seed Sample Data (Optional)
```bash
php artisan db:seed --class=HolidaySeeder
```
This adds Bangladesh national holidays and school dates.

### 3. Access Admin Panel
Navigate to: `http://yourdomain.com/admin/holidays`

---

## 📝 Adding Holidays

### Method 1: Single Holiday (UI)
1. Click **"Add Holiday"** button
2. Fill in the form:
   - **Date**: YYYY-MM-DD format
   - **Title**: Holiday name (e.g., "Independence Day")
   - **Applies To**: 
     - `All` - affects both students & staff
     - `Staff` - affects only employees
     - `Students` - affects only students
   - **Description**: Optional notes
3. Click **"Create Holiday"**

### Method 2: Bulk Import (UI)
1. Click **"Bulk Import"** button
2. Paste JSON with holidays list
3. Click **"Import Holidays"**

**JSON Format**:
```json
[
  {
    "date": "2026-03-26",
    "title": "Independence Day",
    "applies_to": "all",
    "description": "National holiday"
  },
  {
    "date": "2026-05-01",
    "title": "Labor Day",
    "applies_to": "staff"
  }
]
```

### Method 3: Tinker (Quick CLI)
```bash
php artisan tinker
```

```php
// Add single holiday
Holiday::create([
    'date' => '2026-03-26',
    'title' => 'Independence Day',
    'applies_to' => 'all',
    'description' => 'National holiday'
]);

// Add multiple
Holiday::insert([
    ['date' => '2026-05-01', 'title' => 'Labor Day', 'applies_to' => 'staff'],
    ['date' => '2026-06-01', 'title' => 'Summer Starts', 'applies_to' => 'students'],
]);
```

### Method 4: Database Seeder
Create a new migration file:
```bash
php artisan make:seeder SchoolHolidaySeeder
```

Edit `database/seeders/SchoolHolidaySeeder.php`:
```php
<?php
namespace Database\Seeders;

use App\Models\Holiday;
use Illuminate\Database\Seeder;

class SchoolHolidaySeeder extends Seeder
{
    public function run(): void
    {
        Holiday::insert([
            [
                'date' => '2026-03-26',
                'title' => 'Independence Day',
                'applies_to' => 'all',
                'created_at' => now(),
                'updated_at' => now(),
            ],
            // ... more holidays
        ]);
    }
}
```

Run it:
```bash
php artisan db:seed --class=SchoolHolidaySeeder
```

---

## 👥 Applies To Options

| Option | Effect | Use Case |
|--------|--------|----------|
| **All** | Affects students & staff | National holidays (Independence Day, etc) |
| **Staff** | Affects only employees | Staff training days, board meetings |
| **Students** | Affects only students | Summer vacation, semester breaks |

---

## 📊 How Holidays Affect Attendance

When a holiday is declared, the attendance processing automatically updates employee records:

```
Holiday declared (applies_to = 'staff')
        ↓
php artisan attendance:build-daily --date=2026-03-26
        ↓
AttendanceDailySummary.attendance_status = 'holiday'
        ↓
Employee marked as "Holiday" (not "Absent")
```

**Status Priority**:
1. Approved Leave → `'leave'`
2. Declared Holiday → `'holiday'`  ← NEW
3. Weekly Off → `'off_day'`
4. Biometric Data → `'present'` / `'partial'` / `'absent'`

---

## ⚙️ System Requirements

**Database**: MySQL 8.0+  
**Laravel**: 11.x  
**PHP**: 8.1+

**Holidays Table Columns**:
```sql
id              INT PRIMARY KEY
date            DATE (unique)
title           VARCHAR(255)
applies_to      ENUM('students', 'staff', 'all')
description     TEXT (nullable)
created_at      TIMESTAMP
updated_at      TIMESTAMP
```

---

## 🛠️ Technical Details

### Routes

| Method | Route | Name | Description |
|--------|-------|------|-------------|
| GET | `/admin/holidays` | `admin.holidays.index` | List all holidays |
| GET | `/admin/holidays/create` | `admin.holidays.create` | Create form |
| POST | `/admin/holidays` | `admin.holidays.store` | Store new holiday |
| GET | `/admin/holidays/{id}/edit` | `admin.holidays.edit` | Edit form |
| PUT | `/admin/holidays/{id}` | `admin.holidays.update` | Update holiday |
| DELETE | `/admin/holidays/{id}` | `admin.holidays.destroy` | Delete holiday |
| GET | `/admin/holidays/bulk/create` | `admin.holidays.bulk` | Bulk import form |
| POST | `/admin/holidays/bulk/store` | `admin.holidays.bulk.store` | Store bulk import |

### Models

**Holiday Model**: `app/Models/Holiday.php`
```php
Holiday::forStaff();      // Get staff-applicable holidays
Holiday::forStudents();   // Get student-applicable holidays

// Query
Holiday::whereDate('date', '2026-03-26')->first();
```

### Controller

**HolidayController**: `app/Http/Controllers/admin/HolidayController.php`
- `index()` - List holidays
- `create()` - Show create form
- `store()` - Save holiday
- `edit()` - Show edit form
- `update()` - Save changes
- `destroy()` - Delete holiday
- `bulkCreate()` - Show bulk import form
- `bulkStore()` - Process bulk import

### Command

```bash
# Process attendance for a specific date
php artisan attendance:build-daily --date=2026-03-26

# Process attendance for a date range
php artisan attendance:build-daily --from=2026-03-01 --to=2026-03-31

# Process for specific employee
php artisan attendance:build-daily --date=2026-03-26 --employee_id=5
```

---

## 📖 Examples

### Example 1: Add National Holiday
```bash
php artisan tinker
> Holiday::create([
    'date' => '2026-03-26',
    'title' => 'Independence Day',
    'applies_to' => 'all'
])
```

### Example 2: Bulk Import Bangladesh Holidays
Via admin panel, paste this JSON:
```json
[
  {"date": "2026-02-21", "title": "Language Day", "applies_to": "all"},
  {"date": "2026-03-17", "title": "Mujib's Birthday", "applies_to": "all"},
  {"date": "2026-03-26", "title": "Independence Day", "applies_to": "all"},
  {"date": "2026-04-13", "title": "Bangla New Year", "applies_to": "all"},
  {"date": "2026-05-01", "title": "Labor Day", "applies_to": "all"},
  {"date": "2026-08-15", "title": "National Mourning", "applies_to": "all"},
  {"date": "2026-12-16", "title": "Victory Day", "applies_to": "all"}
]
```

### Example 3: Summer Vacation (Students Only)
Via admin panel:
- **Date**: 2026-06-01
- **Title**: Summer Vacation Starts
- **Applies To**: Students
- **Description**: School summer break

### Example 4: Check Holidays in Admin Panel
1. Go to `/admin/holidays`
2. See table with all holidays
3. Filter by date, apply_to, or use search
4. Click Edit/Delete as needed

---

## 🧪 Testing

### Verify Setup
```bash
# Check tables exist
php artisan tinker
> Schema::hasTable('holidays') // true
> Holiday::count()  // Should show holidays count
```

### Test Attendance Integration
```bash
# Create test holiday
> Holiday::create(['date' => '2026-05-20', 'title' => 'Test', 'applies_to' => 'staff'])

# Build attendance for that date
exit
php artisan attendance:build-daily --date=2026-05-20

# Verify result
php artisan tinker
> AttendanceDailySummary::whereDate('date', '2026-05-20')->pluck('attendance_status')->unique()
// Should show ['holiday']
```

---

## 📋 Troubleshooting

### Issue: Holiday not affecting attendance
**Solution**: Run the attendance build command:
```bash
php artisan attendance:build-daily --date=2026-03-26
```

### Issue: Can't add holiday - date already exists
**Solution**: Edit existing holiday or delete first

### Issue: Holidays showing for wrong category (students instead of staff)
**Solution**: Check `applies_to` value in database

### Issue: Permission denied when accessing admin panel
**Solution**: Assign `admin` role to user:
```php
$user->assignRole('admin');
```

---

## 🔄 Workflow

```
Admin Panel (Add Holiday)
    ↓
Holiday Model (Stored in DB)
    ↓
AttendanceBuildDailySummary Command (Run daily or manual)
    ↓
Holiday Check (Is date a holiday for this employee?)
    ↓
AttendanceDailySummary.attendance_status = 'holiday'
    ↓
Reports & Dashboard (Show correct status)
```

---

## 📚 Related Documentation

- [Holiday Attendance Integration](HOLIDAY_ATTENDANCE_INTEGRATION.md)
- [Attendance Command Guide](app/Console/Commands/AttendanceBuildDailySummary.php)
- [Employee Attendance System](app/Models/AttendanceDailySummary.php)

---

## ✨ Features Coming Soon

- Calendar view of holidays
- Holiday statistics dashboard
- Export holidays to CSV/Excel
- Recurring holidays (annual)
- Holiday notifications
- Attendance impact preview

---

**Last Updated**: May 18, 2026  
**Status**: ✅ Production Ready