Anjing Webshells

Website : rimsha.abasa.com
: / var / www / mudeerapi.abasa.com / nodetest-backup30April26 /
Filename : TENURE_MONTH_SELECTION_SUMMARY.md
back
# Tenure Month Selection - Implementation Summary

## Overview
Implemented dynamic tenure display that adjusts based on the selected month/date range across all screens showing attendance summaries.

## Problem
Previously, attendance summary cards always showed the "current tenure" (based on today's date), even when users filtered by a different month (e.g., August 2025). This was confusing because:
- The summary showed "Current Tenure (Jan 1, 2026 – Dec 31, 2026)"
- But the filtered data was from August 2025 (which belongs to a different tenure)

## Solution
The system now shows the **tenure that contains the selected month**, not always the current tenure.

## How It Works

### Backend (`leave.controller.js`)
Both `/user/:id/leave-info` and `getEmployeeStats` already supported this:

1. **`getUserLeaveInfo`** (line 288-384):
   - Accepts `?month=yyyy-MM` query parameter (line 322-327)
   - Derives target date from the month parameter (defaults to today if not provided)
   - Calculates which tenure contains that target date (line 330)
   - Returns leave statistics for **that specific tenure** (not always the current one)
   - Returns `tenureLabel` with proper formatting, e.g.:
     - `"Current Tenure (Jan 1, 2026 – Dec 31, 2026)"` if viewing current month
     - `"Tenure 1 (Jan 15, 2025 – Jan 14, 2026)"` if viewing a past tenure

2. **`getEmployeeStats`** (line 701-783):
   - Accepts a `targetDate` parameter (used by leave request detail page)
   - Calculates tenure for that date
   - Returns statistics for that specific tenure

3. **Backward Compatibility**:
   - Added `leaveYear: tenureStart.getUTCFullYear()` to responses (line 362, 745)
   - This ensures frontend components that still use `leaveYear` for fallback display continue to work
   - The `leaveYear` is derived from the tenure's start year, NOT from today's date

### Frontend (Already Implemented)

#### Attendance Page (`attendance/page.tsx`)
- Line 437-448: Fetches leave info with `?month=${dateValue}` parameter
- Line 1078-1094: Displays `AttendanceSummaryCard` with `tenureLabel` from API
- When user changes month filter, the API is re-queried with the new month
- Summary card automatically updates to show the correct tenure

#### Leave Request Add Page (`leave-request/add/page.tsx`)
- Line 187: Passes `?month=${currentMonthParam}` to API
- Line 200: (Direct mode) Also passes month parameter for each selected employee
- Line 445-461: Displays `AttendanceSummaryCard` with `tenureLabel`
- Line 512-526: (Direct mode) Shows summary for each selected employee with correct tenure

#### Leave Request Detail Page (`leave-request/[id]/page.tsx`)
- Uses `employeeStats` from API which is calculated based on the leave request's `startDate`
- Line 360: Shows `tenureLabel` or falls back to `leaveYear`
- Ensures the summary always shows the tenure relevant to that specific leave request

## `AttendanceSummaryCard` Component
- Line 17-19: Already accepts `tenureLabel` prop
- Line 35: Uses `tenureLabel` in heading if available, otherwise falls back to `leaveYear`
- Line 89: Shows tenure label at bottom of card

## Key Behaviors

### Example 1: Viewing Current Month (April 2026)
- User has tenure: Jan 1, 2026 – Dec 31, 2026
- Viewing April 2026
- Summary shows: "Attendance Summary – Current Tenure (Jan 1, 2026 – Dec 31, 2026)"
- Statistics: Paid leaves 6/12 (counted from Jan 1 to now)

### Example 2: Viewing Past Month (August 2025)
- User has tenure: Jan 15, 2025 – Jan 14, 2026
- Viewing August 2025
- Summary shows: "Attendance Summary – Tenure 1 (Jan 15, 2025 – Jan 14, 2026)"
- Statistics: Paid leaves 13/12 (counted from Jan 15, 2025 to Jan 14, 2026)

### Example 3: Leave Request Detail
- Leave request from June 2025
- Summary automatically shows the tenure that contains June 2025
- User doesn't need to manually filter

## Files Modified

### Backend
- `src/controllers/leave.controller.js`
  - Line 362: Added `leaveYear` derived from tenure start year to `getUserLeaveInfo` response
  - Line 745: Added `leaveYear` derived from tenure start year to `getEmployeeStats` return value
  - Removed `tenureStart` and `tenureEnd` raw dates from response (keeping only `tenureLabel`)

### Frontend
- No changes required! Already working correctly because:
  - Already passing `?month=` parameter to API
  - Already displaying `tenureLabel` from API response
  - Already re-fetching when month changes

## Testing Checklist

- [x] Backend returns correct tenure for selected month
- [x] Backend includes `leaveYear` for backward compatibility
- [ ] Manual: Attendance page shows correct tenure when changing month filter
- [ ] Manual: Leave request add page shows correct tenure when changing month
- [ ] Manual: Leave request detail page shows tenure for request's date
- [ ] Manual: Summary statistics match the displayed tenure period
- [ ] Manual: Verify no console errors in frontend

## Notes
- The `leaveYear` field returned by the API is now **derived** from the tenure's start year, not from the user document or today's date
- The `leaveYear` field in the `user` model has been completely removed (as part of previous migration)
- All leave tracking is now purely tenure-based
- The `tenureLabel` is the primary display field, `leaveYear` is only for backward compatibility