feat: Improve balance synchronization and fix orphaned links

- Display a warning for orphaned transferred days
- Enable synchronize button for orphaned days
- Add logic to fix orphaned transferred days links
- Improve serializer to fetch previous year's balance directly
- Update log messages for balance and transferred days fixes

Author: Mahmoud-Emad

client/src/components/dashboard/AuditUserBalance.vue

@@ -45,7 +45,7 @@
                     <div class="d-flex justify-space-between align-end mb-4">
                         <div>
                             <h3 class="text-h6 font-weight-bold">Audit Results for {{ reportData.user_full_name
-                            }}</h3>
+                                }}</h3>
                             <div class="text-body-2 text-medium-emphasis">Period: {{ reportData.year }} |
                                 Reason: <span class="text-capitalize">{{ reportData.reason }}</span></div>
                         </div>
@@ -136,14 +136,23 @@
 
                     <v-alert v-if="reportData.discrepancy" type="info" variant="tonal" class="mt-6 border-red"
                         color="error" icon="mdi-alert-circle">
-                        <div class="font-weight-bold">Correction Required</div>
+                        <div class="font-weight-bold">Balance Discrepancy Detected</div>
                         The database balance is out of sync. This action will synchronize the records and notify
                         the user.
                     </v-alert>
 
+                    <v-alert v-if="reportData.transferred_days_orphaned" type="warning" variant="tonal" class="mt-4"
+                        icon="mdi-link-variant-off">
+                        <div class="font-weight-bold">Orphaned Transferred Balance Link</div>
+                        The {{ reportData.year + 1 }} balance is pointing to an outdated transferred days record
+                        (showing {{ reportData.next_year_transferred_value }} instead of {{
+                            reportData.expected_remaining }}).
+                        This will be fixed when you click the synchronize button.
+                    </v-alert>
+
                     <div class="d-flex justify-end mt-4">
-                        <v-btn v-if="reportData.discrepancy" color="error" @click="showFixConfirm = true"
-                            :loading="isFixing" class="text-none font-weight-bold px-8">
+                        <v-btn v-if="reportData.discrepancy || reportData.transferred_days_orphaned" color="error"
+                            @click="showFixConfirm = true" :loading="isFixing" class="text-none font-weight-bold px-8">
                             Synchronize User Balance
                         </v-btn>
                     </div>
@@ -251,6 +260,9 @@ export default {
                 } else {
                     addLog('Calculations match database records.', 'success')
                 }
+                if (result.transferred_days_orphaned) {
+                    addLog(`ALERT: ${selectedYear.value + 1} transferred balance is incorrectly linked (shows ${result.next_year_transferred_value} instead of ${result.expected_remaining}).`, 'warn')
+                }
             } catch (err: any) {
                 const errorMsg = err.response?.data?.message || err.message || 'Unknown error'
                 addLog(`Error generating report: ${errorMsg}`, 'error')
@@ -271,8 +283,16 @@ export default {
                     reason: selectedReason.value
                 })
 
-                addLog(`SUCCESS: Balance updated to ${result.new_remaining}.`, 'success')
-                addLog(`Notification sent to user. Process complete.`, 'info')
+                if (result.balance_fixed) {
+                    addLog(`Balance updated to ${result.new_remaining}.`, 'success')
+                }
+                if (result.transferred_days_fixed) {
+                    addLog(`Fixed orphaned transferred balance link for ${selectedYear.value + 1}.`, 'success')
+                }
+                if (result.balance_fixed) {
+                    addLog(`Notification sent to user.`, 'info')
+                }
+                addLog(`Process complete.`, 'success')
 
                 // Refresh report
                 await generateReport()

server/cshr/serializers/vacations.py

@@ -188,10 +188,28 @@ def get_transferred_days(
         self, obj: UserVacationBalance
     ) -> VacationBalanceSerializer:
         """
-        this function serialize transferred days
+        Serialize transferred days by directly fetching the previous year's remaining balance.
+        This is more reliable than using the transferred_days relationship which can become orphaned.
+        Returns None if the balance is locked (not available for use).
         """
-        return (
-            None
-            if not obj.transferred_days
-            else VacationBalanceSerializer(obj.transferred_days).data
-        )
+        # Always fetch the previous year's remaining_days directly for accuracy
+        from cshr.models.vacations import UserVacationBalance as UVB
+        
+        previous_year_balance = UVB.objects.filter(
+            user=obj.user, year=obj.year - 1
+        ).select_related("remaining_days").first()
+        
+        if previous_year_balance and previous_year_balance.remaining_days:
+            # If the balance is locked, don't return it (user can't use old balance)
+            if previous_year_balance.remaining_days.is_locked:
+                return None
+            return VacationBalanceSerializer(previous_year_balance.remaining_days).data
+        
+        # Fallback to the stored transferred_days if no previous year exists
+        # Also check if it's locked
+        if obj.transferred_days:
+            if obj.transferred_days.is_locked:
+                return None
+            return VacationBalanceSerializer(obj.transferred_days).data
+        
+        return None

server/cshr/services/balance.py

@@ -90,6 +90,14 @@ def audit_user_balance(user: User, year: int, reason: str) -> Dict[str, Any]:
 
         expected_remaining = total_quota - total_recalc_current
 
+        # Check if next year's transferred_days is correctly linked
+        next_year_balance = UserVacationBalance.objects.filter(user=user, year=year + 1).first()
+        transferred_days_orphaned = False
+        if next_year_balance and next_year_balance.transferred_days:
+            # Check if it's pointing to the correct object (this year's remaining_days)
+            if next_year_balance.transferred_days.id != balance_obj.remaining_days.id:
+                transferred_days_orphaned = True
+
         return {
             "user_full_name": user.full_name,
             "year": year,
@@ -99,14 +107,37 @@ def audit_user_balance(user: User, year: int, reason: str) -> Dict[str, Any]:
             "expected_remaining": expected_remaining,
             "vacations": reports,
             "discrepancy": expected_remaining != current_db_remaining,
+            "transferred_days_orphaned": transferred_days_orphaned,
+            "next_year_transferred_value": getattr(next_year_balance.transferred_days, reason, None) if (next_year_balance and next_year_balance.transferred_days) else None,
         }
 
+    @staticmethod
+    def fix_transferred_days_link(user: User, year: int) -> bool:
+        """
+        Fixes the transferred_days relationship for the next year's balance.
+        Returns True if a fix was applied.
+        """
+        current_balance = UserVacationBalance.objects.filter(user=user, year=year).first()
+        next_year_balance = UserVacationBalance.objects.filter(user=user, year=year + 1).first()
+        
+        if not current_balance or not next_year_balance:
+            return False
+        
+        if next_year_balance.transferred_days and next_year_balance.transferred_days.id != current_balance.remaining_days.id:
+            # Fix the orphaned reference
+            next_year_balance.transferred_days = current_balance.remaining_days
+            next_year_balance.save()
+            return True
+        
+        return False
+
     @staticmethod
     def fix_user_balance(
         user: User, year: int, reason: str, admin_sender: Optional[User] = None
     ) -> Dict[str, Any]:
         """
         Recalculates and fixes the user's balance. Sends a notification if fixed.
+        Also fixes orphaned transferred_days references.
         """
         audit_result = BalanceService.audit_user_balance(user, year, reason)
         if not audit_result:
@@ -147,10 +178,17 @@ def fix_user_balance(
                 )
                 notification_service.send()
 
+        # Always try to fix orphaned transferred_days link (independent of balance discrepancy)
+        transferred_days_fixed = False
+        if audit_result.get("transferred_days_orphaned"):
+            transferred_days_fixed = BalanceService.fix_transferred_days_link(user, year)
+
         return {
             "new_remaining": audit_result["expected_remaining"],
             "total_consumed": audit_result["total_quota"]
             - audit_result["expected_remaining"],
+            "balance_fixed": audit_result["discrepancy"],
+            "transferred_days_fixed": transferred_days_fixed,
         }
 
     @staticmethod