# Leave Approval Workflow Documentation

## Overview
The leave approval system implements a **multi-level approval workflow** where the approval path depends on the **student type** (hostel or day scholar). The **Assistant Director has the final approval authority** for all leave requests.

---

## Approval Flow Diagram

### For Hostel Students (3 Levels):
```
Student (applies leave)
    ↓
Level 1: Training Officer (approves/rejects)
    ↓
Level 2: Warden (approves/rejects)
    ↓
Level 3: Assistant Director (final approval/rejection)
    ↓
APPROVED ✓ or REJECTED ✗
```

### For Day Scholar Students (2 Levels):
```
Student (applies leave)
    ↓
Level 1: Training Officer (approves/rejects)
    ↓
Level 2: Assistant Director (final approval/rejection)
    ↓
APPROVED ✓ or REJECTED ✗
```

---

## Director's Role
**The Director has VIEW-ONLY access** to all leave requests. Directors cannot approve or reject leaves.
- Directors can view all leave requests through the dedicated view interface
- Directors can see the approval history and current status of any leave
- All approval decisions are made by the Assistant Director at their respective levels
- Directors can access reports and analytics of the leave system for oversight purposes

---

## Key Implementation Details

### Database Fields:
- `LeaveRequest.student_type`: Either "hostel" or "scholar" (set by student during leave application)
- `LeaveRequest.current_level`: Current approval level (1, 2, or 3 depending on student type)
- `LeaveRequest.status`: "pending", "forwarded", "approved", or "rejected"
- `ApprovalLog.level`: The approval level when the decision was made
- `ApprovalLog.decision`: "approved" or "rejected"
- `ApprovalLog.remarks`: Optional comments from the approver

### Level Mapping:

| Level | Hostel Students | Day Scholar Students |
|-------|-----------------|----------------------|
| 1     | Training Officer | Training Officer     |
| 2     | Warden | Assistant Director (Final) |
| 3     | Assistant Director (Final) | N/A |

---

## Approval Process Flow

### 1. Student Submits Leave Request
**File:** `StudentLeaveController::store()`
- Student selects `student_type` ("hostel" or "scholar")
- Leave request created with `current_level = 1`
- Initial status: "pending"

### 2. Training Officer Approval (Level 1)
**File:** `ApprovalController::show()` and `process()`
- Training Officer reviews the leave request
- Decision: Approve or Reject
- If **Approved**: Request moves to Level 2
- If **Rejected**: Request marked as "rejected", student notified

### 3. Level 2 Approval (Warden or Assistant Director)
**File:** `LeaveApprovalService::handleApproval()`
- If **hostel student** → **Warden** approves, request moves to Level 3
- If **day scholar** → **Assistant Director** approves (final)
- Decision: Approve or Reject
- If **Rejected**: Request marked as "rejected", student notified
- If **Approved**:
  - Hostel: Moves to Level 3 (Assistant Director - final)
  - Day Scholar: Marked as "approved" (final)

### 4. Level 3 Approval (Assistant Director - Hostel Only)
**File:** `LeaveApprovalService::handleApproval()`
- Only for **hostel students** (final approval)
- **Assistant Director** makes the final decision
- If **Approved**: Leave officially approved, student notified
- If **Rejected**: Leave rejected, student notified
- Process complete

### 5. Director View (View-Only)
**File:** `ApprovalController::viewAllLeaves()` and `viewLeaveDetail()`
- Director can view all leave requests
- Director can see approval history and current status
- Director cannot approve or reject leaves
- Routes:
  - `/approvals/view-all` - View all leaves
  - `/approvals/view/{leaveRequest}` - View specific leave detail

---

## Service Methods

### `LeaveApprovalService::handleApproval()`
Handles approval/rejection logic:
```php
handleApproval(LeaveRequest $leave, User $approver, string $decision, ?string $remarks)
```
- Creates approval log entry
- Handles rejections (stops process immediately)
- Automatically forwards to next level if approved

### `ApprovalController::viewAllLeaves()`
Returns view of all leaves with pagination:
```php
viewAllLeaves() // Returns view('approval.view-all')
```
- Shows all leave requests in a table format
- Director-only access
- Read-only interface

### `ApprovalController::viewLeaveDetail()`
Returns detailed view of a single leave:
```php
viewLeaveDetail(LeaveRequest $leaveRequest) // Returns view('approval.view-detail')
```
- Shows complete leave details and approval history
- Director-only access
- Read-only interface
- Sends notifications to next approver
- Final level approval marks leave as "approved"

### `LeaveApprovalService::getNextApprovalLevel()`
Determines next level based on current level and student type:
- **Hostel**: 1→2→3→4
- **Day Scholar**: 1→2→3

---

## File References

**Key Files:**
- `app/Services/LeaveApprovalService.php` - Approval workflow logic
- `app/Http/Controllers/ApprovalController.php` - Approval interface & validation
- `app/Http/Controllers/DashboardController.php` - Dashboard filtering by role/level
- `app/Models/ApprovalLog.php` - Approval log & level name mapping
- `resources/views/approval/review.blade.php` - Approval form interface

---

## Service Methods

### `LeaveApprovalService::handleApproval()`
Handles approval/rejection logic:
```php
handleApproval(LeaveRequest $leave, User $approver, string $decision, ?string $remarks)
```
- Creates approval log entry
- Handles rejections (stops process)
- Automatically forwards to next level if approved
- Sends notifications to next approver

### `LeaveApprovalService::getNextApprovalLevel()`
Returns next approval level (2 or 3)

### `LeaveApprovalService::getApproverRoleForLevel()`
Returns the role for a given level and student type:
```php
// Level 1 → always 'training_officer'
// Level 2 → 'warden' (hostel) or 'assistant_director' (scholar)
// Level 3 → always 'director'
```

### `LeaveApprovalService::getPendingRequestsForRole()`
Gets all leaves pending at a user's level:
```php
getPendingRequestsForRole(string $role) // returns Collection
```

---

## Notification System

### Notifications are sent to:
1. **Training Officer**: When student submits leave request
2. **Warden** (for hostel) / **Assistant Director** (for scholar): When TO approves and forwards
3. **Director**: When Level 2 approver approves and forwards
4. **Student**:
   - When request is rejected (at any level)
   - When request is finally approved
   - Status updates for each forward

---

## Database Queries

### Get all leaves at Training Officer level:
```sql
SELECT * FROM leave_requests WHERE current_level = 1 AND status != 'approved' AND status != 'rejected';
```

### Get all leaves at Warden level (for hostel students):
```sql
SELECT * FROM leave_requests WHERE current_level = 2 AND student_type = 'hostel' AND status != 'approved' AND status != 'rejected';
```

### Get all leaves at Assistant Director level (for day scholars):
```sql
SELECT * FROM leave_requests WHERE current_level = 2 AND student_type = 'scholar' AND status != 'approved' AND status != 'rejected';
```

### Get all leaves at Director level:
```sql
SELECT * FROM leave_requests WHERE current_level = 3 AND status != 'approved' AND status != 'rejected';
```

---

## Testing Scenarios

### Scenario 1: Hostel Student Leave (Approved Path)
1. Create student with student_type = "hostel"
2. Student submits leave request
3. Expected: current_level = 1, status = "pending"
4. Training Officer approves
5. Expected: current_level = 2, status = "forwarded"
6. Warden approves
7. Expected: current_level = 3, status = "forwarded"
8. Director approves
9. Expected: status = "approved"

### Scenario 2: Day Scholar Leave (Rejected at Level 2)
1. Create student with student_type = "scholar"
2. Student submits leave request
3. Expected: current_level = 1, status = "pending"
4. Training Officer approves
5. Expected: current_level = 2, status = "forwarded"
6. Assistant Director rejects
7. Expected: status = "rejected"
8. Student receives rejection notification

### Scenario 3: Hostel Student Leave (Rejected at Level 1)
1. Create student with student_type = "hostel"
2. Student submits leave request
3. Training Officer rejects
4. Expected: status = "rejected"
5. Request doesn't proceed to Warden level

---

## Files Modified

- `app/Services/LeaveApprovalService.php` - Core approval logic
- `app/Http/Controllers/StudentLeaveController.php` - Leave submission
- `app/Http/Controllers/ApprovalController.php` - Approval interface
- `app/Models/ApprovalLog.php` - Level name mapping
- `routes/web.php` - Approval routes for Training Officer, Warden, and Assistant Director

---

## Configuration Summary

**Leave Statuses:**
- `pending` - Awaiting first approval (Training Officer)
- `forwarded` - Approved at current level, moved to next
- `approved` - Fully approved at all levels
- `rejected` - Rejected at any level

**Approval Levels:**
- Level 1: Training Officer (everyone)
- Level 2: Warden (hostel) or Assistant Director (day scholar - final)
- Level 3: Assistant Director (hostel - final)

**Student Types:**
- `hostel` - Hostel student (route: TO → Warden → Assistant Director)
- `scholar` - Day scholar (route: TO → Assistant Director)