marco.pms.api/Marco.Pms.Services/Service/ProjectServices.cs

using AutoMapper;
using AutoMapper.QueryableExtensions;
using Marco.Pms.DataAccess.Data;
using Marco.Pms.Model.Activities;
using Marco.Pms.Model.Dtos.Project;
using Marco.Pms.Model.Dtos.Projects;
using Marco.Pms.Model.Dtos.Util;
using Marco.Pms.Model.Employees;
using Marco.Pms.Model.Entitlements;
using Marco.Pms.Model.Master;
using Marco.Pms.Model.MongoDBModels.Project;
using Marco.Pms.Model.OrganizationModel;
using Marco.Pms.Model.Projects;
using Marco.Pms.Model.TenantModels;
using Marco.Pms.Model.Utilities;
using Marco.Pms.Model.ViewModels.Activities;
using Marco.Pms.Model.ViewModels.Employee;
using Marco.Pms.Model.ViewModels.Master;
using Marco.Pms.Model.ViewModels.Organization;
using Marco.Pms.Model.ViewModels.Projects;
using Marco.Pms.Services.Helpers;
using Marco.Pms.Services.Service.ServiceInterfaces;
using MarcoBMS.Services.Helpers;
using MarcoBMS.Services.Service;
using Microsoft.CodeAnalysis;
using Microsoft.EntityFrameworkCore;
using Project = Marco.Pms.Model.Projects.Project;

namespace Marco.Pms.Services.Service
{
    public class ProjectServices : IProjectServices
    {
        private readonly IDbContextFactory<ApplicationDbContext> _dbContextFactory;
        private readonly IServiceScopeFactory _serviceScopeFactory;
        private readonly ApplicationDbContext _context; // Keeping this for direct scoped context use where appropriate
        private readonly ILoggingService _logger;
        private readonly CacheUpdateHelper _cache;
        private readonly IMapper _mapper;
        public ProjectServices(
            IDbContextFactory<ApplicationDbContext> dbContextFactory,
            IServiceScopeFactory serviceScopeFactory,
            ApplicationDbContext context,
            ILoggingService logger,
            CacheUpdateHelper cache,
            IMapper mapper)
        {
            _dbContextFactory = dbContextFactory ?? throw new ArgumentNullException(nameof(dbContextFactory));
            _serviceScopeFactory = serviceScopeFactory ?? throw new ArgumentNullException(nameof(serviceScopeFactory));
            _context = context ?? throw new ArgumentNullException(nameof(context));
            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
            _cache = cache ?? throw new ArgumentNullException(nameof(cache));
            _mapper = mapper ?? throw new ArgumentNullException(nameof(mapper));
        }

        #region =================================================================== Project Get APIs ===================================================================

        public async Task<ApiResponse<object>> GetAllProjectsBasicAsync(Guid tenantId, Employee loggedInEmployee)
        {
            try
            {
                // Step 1: Verify the current user
                if (loggedInEmployee == null)
                {
                    return ApiResponse<object>.ErrorResponse("Unauthorized", "User could not be identified.", 401);
                }

                _logger.LogInfo("Basic project list requested by EmployeeId {EmployeeId}", loggedInEmployee.Id);

                // Step 2: Get the list of project IDs the user has access to
                List<Guid> accessibleProjectIds = await GetMyProjects(tenantId, loggedInEmployee);

                if (accessibleProjectIds == null || !accessibleProjectIds.Any())
                {
                    _logger.LogInfo("No accessible projects found for EmployeeId {EmployeeId}", loggedInEmployee.Id);
                    return ApiResponse<object>.SuccessResponse(new List<ProjectInfoVM>(), "0 records of project fetchd successfully", 200);
                }

                // Step 3: Fetch project ViewModels using the optimized, cache-aware helper
                var projectVMs = await GetProjectInfosByIdsAsync(accessibleProjectIds);

                // Step 4: Return the final list
                _logger.LogInfo("Successfully returned {ProjectCount} projects for EmployeeId {EmployeeId}", projectVMs.Count, loggedInEmployee.Id);
                return ApiResponse<object>.SuccessResponse(projectVMs, $"{projectVMs.Count} records of project fetchd successfully", 200);
            }
            catch (Exception ex)
            {
                // --- Step 5: Graceful Error Handling ---
                _logger.LogError(ex, "An unexpected error occurred in GetAllProjectsBasic for tenant {TenantId}.", tenantId);
                return ApiResponse<object>.ErrorResponse("An internal server error occurred. Please try again later.", null, 500);
            }
        }
        public async Task<ApiResponse<object>> GetAllProjectsAsync(Guid tenantId, Employee loggedInEmployee)
        {
            try
            {
                _logger.LogInfo("Starting GetAllProjects for TenantId: {TenantId}, User: {UserId}", tenantId, loggedInEmployee.Id);

                // --- Step 1: Get a list of project IDs the user can access ---
                List<Guid> projectIds = await GetMyProjects(tenantId, loggedInEmployee);
                if (!projectIds.Any())
                {
                    _logger.LogInfo("User has no assigned projects. Returning empty list.");
                    return ApiResponse<object>.SuccessResponse(new List<ProjectListVM>(), "No projects found for the current user.", 200);
                }

                // --- Step 2: Efficiently handle partial cache hits ---
                _logger.LogInfo("Attempting to fetch details for {ProjectCount} projects from cache.", projectIds.Count);

                // Fetch what we can from the cache.
                var cachedDetails = await _cache.GetProjectDetailsList(projectIds) ?? new List<ProjectMongoDB>();
                var cachedDictionary = cachedDetails.ToDictionary(p => Guid.Parse(p.Id));

                // Identify which projects are missing from the cache.
                var missingIds = projectIds.Where(id => !cachedDictionary.ContainsKey(id)).ToList();

                // Start building the response with the items we found in the cache.
                var responseVms = _mapper.Map<List<ProjectListVM>>(cachedDictionary.Values);

                if (missingIds.Any())
                {
                    // --- Step 3: Fetch ONLY the missing items from the database ---
                    _logger.LogInfo("Cache partial MISS. Found {CachedCount}, fetching {MissingCount} projects from DB.",
                                           cachedDictionary.Count, missingIds.Count);

                    // Call our dedicated data-fetching method for the missing IDs.
                    var newMongoDetails = await FetchAndBuildProjectDetails(missingIds, tenantId);

                    if (newMongoDetails.Any())
                    {
                        // Map the newly fetched items and add them to our response list.
                        responseVms.AddRange(newMongoDetails);
                    }
                }
                else
                {
                    _logger.LogInfo("Cache HIT. All {ProjectCount} projects found in cache.", projectIds.Count);
                }

                // --- Step 4: Return the combined result ---
                _logger.LogInfo("Successfully retrieved a total of {ProjectCount} projects.", responseVms.Count);
                return ApiResponse<object>.SuccessResponse(responseVms, "Projects retrieved successfully.", 200);
            }
            catch (Exception ex)
            {
                // --- Step 5: Graceful Error Handling ---
                _logger.LogError(ex, "An unexpected error occurred in GetAllProjects for tenant {TenantId}.", tenantId);
                return ApiResponse<object>.ErrorResponse("An internal server error occurred. Please try again later.", null, 500);
            }
        }
        public async Task<ApiResponse<object>> GetProjectAsync(Guid id, Guid tenantId, Employee loggedInEmployee)
        {
            try
            {
                using var scope = _serviceScopeFactory.CreateScope();
                var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();
                // --- Step 1: Run independent operations in PARALLEL ---
                // We can check permissions and fetch data at the same time to reduce latency.
                var permissionTask = _permission.HasProjectPermission(loggedInEmployee, id);

                // This helper method encapsulates the "cache-first, then database" logic.
                var projectDataTask = GetProjectDataAsync(id, tenantId);

                // Await both tasks to complete.
                await Task.WhenAll(permissionTask, projectDataTask);

                var hasPermission = await permissionTask;
                var projectVm = await projectDataTask;

                // --- Step 2: Process results sequentially ---

                // 2a. Check for permission first. Forbid() is the idiomatic way to return 403.
                if (!hasPermission)
                {
                    _logger.LogWarning("Access denied for user {UserId} on project {ProjectId}.", loggedInEmployee.Id, id);
                    return ApiResponse<object>.ErrorResponse("Access Denied.", "You do not have permission to access this project.", 403);
                }

                // 2b. Check if the project was found (either in cache or DB).
                if (projectVm == null)
                {
                    _logger.LogInfo("Project with ID {ProjectId} not found.", id);
                    return ApiResponse<object>.ErrorResponse("Project not found.", $"No project found with ID {id}.", 404);
                }

                // 2c. Success. Return the consistent ViewModel.
                _logger.LogInfo("Successfully retrieved project {ProjectId}.", id);
                return ApiResponse<object>.SuccessResponse(projectVm, "Project retrieved successfully.", 200);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "An unexpected error occurred while getting project {ProjectId}", id);
                return ApiResponse<object>.ErrorResponse("An internal server error occurred.", null, 500);
            }
        }
        public async Task<ApiResponse<object>> GetProjectDetailsAsync(Guid id, Guid tenantId, Employee loggedInEmployee)
        {
            try
            {
                _logger.LogInfo("Details requested by EmployeeId: {EmployeeId} for ProjectId: {ProjectId}", loggedInEmployee.Id, id);

                using var scope = _serviceScopeFactory.CreateScope();
                var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();

                // Step 1: Check global view project permission
                var hasViewProjectPermission = await _permission.HasPermission(PermissionsMaster.ViewProject, loggedInEmployee.Id, id);
                if (!hasViewProjectPermission)
                {
                    _logger.LogWarning("ViewProjects permission denied for EmployeeId: {EmployeeId}", loggedInEmployee.Id);
                    return ApiResponse<object>.ErrorResponse("Access denied", "You don't have permission to view projects", 403);
                }

                // Step 2: Check permission for this specific project
                var hasProjectPermission = await _permission.HasProjectPermission(loggedInEmployee, id);
                if (!hasProjectPermission)
                {
                    _logger.LogWarning("Project-specific access denied. EmployeeId: {EmployeeId}, ProjectId: {ProjectId}", loggedInEmployee.Id, id);
                    return ApiResponse<object>.ErrorResponse("Access denied", "You don't have access to this project", 403);
                }

                // Step 3: Fetch project with status
                var projectDetails = await _cache.GetProjectDetails(id);
                ProjectVM? projectVM = null;
                if (projectDetails == null)
                {
                    var project = await _context.Projects
                    .Include(c => c.ProjectStatus)
                    .FirstOrDefaultAsync(c => c.TenantId == tenantId && c.Id == id);

                    projectVM = _mapper.Map<ProjectVM>(project);

                    if (project != null)
                    {
                        await _cache.AddProjectDetails(project);
                    }
                }
                else
                {
                    projectVM = _mapper.Map<ProjectVM>(projectDetails);
                }

                if (projectVM == null)
                {
                    _logger.LogWarning("Project not found. ProjectId: {ProjectId}", id);
                    return ApiResponse<object>.ErrorResponse("Project not found", "Project not found", 404);
                }

                // Step 4: Return result

                _logger.LogInfo("Project details fetched successfully. ProjectId: {ProjectId}", id);
                return ApiResponse<object>.SuccessResponse(projectVM, "Project details fetched successfully", 200);
            }
            catch (Exception ex)
            {
                // --- Step 5: Graceful Error Handling ---
                _logger.LogError(ex, "An unexpected error occurred in Get Project Details for project {ProjectId} for tenant {TenantId}. ", id, tenantId);
                return ApiResponse<object>.ErrorResponse("An internal server error occurred. Please try again later.", null, 500);
            }
        }
        public async Task<ApiResponse<object>> GetProjectDetailsOldAsync(Guid id, Guid tenantId, Employee loggedInEmployee)
        {
            var project = await _context.Projects
                .Where(c => c.TenantId == tenantId && c.Id == id)
                .Include(c => c.ProjectStatus)
                .SingleOrDefaultAsync();

            if (project == null)
            {
                return ApiResponse<object>.ErrorResponse("Project not found", "Project not found", 404);

            }
            else
            {
                ProjectDetailsVM vm = await GetProjectViewModel(id, project);

                OldProjectVM projectVM = new OldProjectVM();
                if (vm.project != null)
                {
                    projectVM.Id = vm.project.Id;
                    projectVM.Name = vm.project.Name;
                    projectVM.ShortName = vm.project.ShortName;
                    projectVM.ProjectAddress = vm.project.ProjectAddress;
                    projectVM.ContactPerson = vm.project.ContactPerson;
                    projectVM.StartDate = vm.project.StartDate;
                    projectVM.EndDate = vm.project.EndDate;
                    projectVM.ProjectStatusId = vm.project.ProjectStatusId;
                }
                projectVM.Buildings = new List<BuildingVM>();
                if (vm.buildings != null)
                {
                    foreach (Building build in vm.buildings)
                    {
                        BuildingVM buildVM = new BuildingVM() { Id = build.Id, Description = build.Description, Name = build.Name };
                        buildVM.Floors = new List<FloorsVM>();
                        if (vm.floors != null)
                        {
                            foreach (Floor floorDto in vm.floors.Where(c => c.BuildingId == build.Id).ToList())
                            {
                                FloorsVM floorVM = new FloorsVM() { FloorName = floorDto.FloorName, Id = floorDto.Id };
                                floorVM.WorkAreas = new List<WorkAreaVM>();

                                if (vm.workAreas != null)
                                {
                                    foreach (WorkArea workAreaDto in vm.workAreas.Where(c => c.FloorId == floorVM.Id).ToList())
                                    {
                                        WorkAreaVM workAreaVM = new WorkAreaVM() { Id = workAreaDto.Id, AreaName = workAreaDto.AreaName, WorkItems = new List<WorkItemVM>() };

                                        if (vm.workItems != null)
                                        {
                                            foreach (WorkItem workItemDto in vm.workItems.Where(c => c.WorkAreaId == workAreaDto.Id).ToList())
                                            {
                                                WorkItemVM workItemVM = new WorkItemVM() { WorkItemId = workItemDto.Id, WorkItem = workItemDto };

                                                workItemVM.WorkItem.WorkArea = new WorkArea();

                                                if (workItemVM.WorkItem.ActivityMaster != null)
                                                {
                                                    workItemVM.WorkItem.ActivityMaster.Tenant = new Tenant();
                                                }
                                                workItemVM.WorkItem.Tenant = new Tenant();

                                                double todaysAssigned = 0;
                                                if (vm.Tasks != null)
                                                {
                                                    var tasks = vm.Tasks.Where(t => t.WorkItemId == workItemDto.Id).ToList();
                                                    foreach (TaskAllocation task in tasks)
                                                    {
                                                        todaysAssigned += task.PlannedTask;
                                                    }
                                                }
                                                workItemVM.TodaysAssigned = todaysAssigned;

                                                workAreaVM.WorkItems.Add(workItemVM);
                                            }
                                        }

                                        floorVM.WorkAreas.Add(workAreaVM);
                                    }
                                }

                                buildVM.Floors.Add(floorVM);
                            }
                        }
                        projectVM.Buildings.Add(buildVM);
                    }
                }
                return ApiResponse<object>.SuccessResponse(projectVM, "Success.", 200);
            }
        }

        #endregion

        #region =================================================================== Project Manage APIs ===================================================================

        public async Task<ApiResponse<object>> CreateProjectAsync(CreateProjectDto model, Guid tenantId, Employee loggedInEmployee)
        {
            // Begin a new scope for service resolution.
            using var scope = _serviceScopeFactory.CreateScope();
            var _firebase = scope.ServiceProvider.GetRequiredService<IFirebaseService>();

            // Step 1: Validate tenant access for the current employee.
            var tenant = await _context.Tenants
                .FirstOrDefaultAsync(t => t.Id == tenantId && t.OrganizationId == loggedInEmployee.OrganizationId);

            if (tenant == null)
            {
                _logger.LogWarning("Access DENIED (OrgId:{OrgId}) by Employee {EmployeeId} for tenantId={TenantId}.",
                    loggedInEmployee.OrganizationId, loggedInEmployee.Id, tenantId);
                return ApiResponse<object>.ErrorResponse("Access Denied", "You do not have permission to create a project for this tenant.", 403);
            }

            // Step 2: Concurrent validation for Promoter and PMC organization existence.
            // Run database queries in parallel for better performance.
            var promoterTask = Task.Run(async () =>
            {
                await using var context = await _dbContextFactory.CreateDbContextAsync();
                return await context.Organizations.FirstOrDefaultAsync(o => o.Id == model.PromoterId);
            });
            var pmcTask = Task.Run(async () =>
            {
                await using var context = await _dbContextFactory.CreateDbContextAsync();
                return await context.Organizations.FirstOrDefaultAsync(o => o.Id == model.PMCId);
            });

            await Task.WhenAll(promoterTask, pmcTask);

            var promoter = promoterTask.Result;
            var pmc = pmcTask.Result;

            if (promoter == null)
            {
                _logger.LogWarning("Promoter check failed. PromoterId={PromoterId} not found.", model.PromoterId);
                return ApiResponse<object>.ErrorResponse("Promoter not found", "Promoter not found in database.", 404);
            }
            if (pmc == null)
            {
                _logger.LogWarning("PMC check failed. PMCId={PMCId} not found.", model.PMCId);
                return ApiResponse<object>.ErrorResponse("PMC not found", "PMC not found in database.", 404);
            }

            // Step 3: Prepare the project entity.
            var loggedInUserId = loggedInEmployee.Id;
            var project = _mapper.Map<Project>(model);
            project.TenantId = tenantId;

            // Step 4: Save the new project to the database.
            try
            {
                _context.Projects.Add(project);
                await _context.SaveChangesAsync();
                _logger.LogInfo("Project {ProjectId} created successfully for TenantId={TenantId}, by Employee {EmployeeId}.",
                    project.Id, tenantId, loggedInUserId);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "DB Failure: Project creation failed for TenantId={TenantId}. Rolling back.", tenantId);
                return ApiResponse<object>.ErrorResponse("An error occurred while saving the project.", ex.Message, 500);
            }

            // Step 5: Perform non-critical post-save side effects (e.g., caching) in parallel.
            try
            {
                var cacheAddDetailsTask = _cache.AddProjectDetails(project);
                var cacheClearListTask = _cache.ClearAllProjectIdsByPermissionId(PermissionsMaster.ManageProject, tenantId);

                await Task.WhenAll(cacheAddDetailsTask, cacheClearListTask);

                _logger.LogInfo("Cache updated for ProjectId={ProjectId} after creation.", project.Id);
            }
            catch (Exception ex)
            {
                // Log the issue but do not interrupt the user flow.
                _logger.LogError(ex, "Post-save cache operation failed for ProjectId={ProjectId}.", project.Id);
            }

            // Step 6: Fire-and-forget push notification for post-creation event. Designed to be non-blocking.
            _ = Task.Run(async () =>
            {
                try
                {
                    var name = $"{loggedInEmployee.FirstName} {loggedInEmployee.LastName}";
                    await _firebase.SendModifyProjectMessageAsync(project, name, false, tenantId);
                    _logger.LogInfo("Push notification sent for ProjectId={ProjectId} ({Name}).", project.Id, name);
                }
                catch (Exception ex)
                {
                    _logger.LogError(ex, "Push notification sending failed for ProjectId={ProjectId}.", project.Id);
                }
            });

            // Step 7: Return success response as soon as critical operation is complete.

            var projectVM = _mapper.Map<ProjectVM>(project);
            projectVM.Promoter = _mapper.Map<BasicOrganizationVm>(promoter);
            projectVM.PMC = _mapper.Map<BasicOrganizationVm>(pmc);

            _logger.LogInfo("Returning success response for ProjectId={ProjectId}.", project.Id);

            return ApiResponse<object>.SuccessResponse(projectVM, "Project created successfully.", 200);
        }

        /// <summary>
        /// Updates an existing project's details.
        /// This endpoint is secure, handles concurrency, and performs non-essential tasks in the background.
        /// </summary>
        /// <param name="id">The ID of the project to update.</param>
        /// <param name="updateProjectDto">The data to update the project with.</param>
        /// <returns>An ApiResponse confirming the update or an appropriate error.</returns>
        public async Task<ApiResponse<object>> UpdateProjectAsync(Guid id, UpdateProjectDto model, Guid tenantId, Employee loggedInEmployee)
        {
            using var scope = _serviceScopeFactory.CreateScope();
            var _firebase = scope.ServiceProvider.GetRequiredService<IFirebaseService>();

            try
            {
                var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();
                // --- Step 1: Fetch the Existing Entity from the Database ---
                // This is crucial to avoid the data loss bug. We only want to modify an existing record.
                var existingProject = await _context.Projects
                    .Where(p => p.Id == id && p.TenantId == tenantId)
                    .SingleOrDefaultAsync();

                // 1a. Existence Check
                if (existingProject == null)
                {
                    _logger.LogWarning("Attempt to update non-existent project with ID {ProjectId} by user {UserId}.", id, loggedInEmployee.Id);
                    return ApiResponse<object>.ErrorResponse("Project not found.", $"No project found with ID {id}.", 404);
                }

                var tenant = await _context.Tenants
               .FirstOrDefaultAsync(t => t.Id == tenantId && t.OrganizationId == loggedInEmployee.OrganizationId);

                if (tenant == null && existingProject.PMCId == loggedInEmployee.OrganizationId)
                {
                    _logger.LogWarning("Access DENIED (OrgId:{OrgId}) by Employee {EmployeeId} for tenantId={TenantId}.",
                        loggedInEmployee.OrganizationId, loggedInEmployee.Id, tenantId);
                    return ApiResponse<object>.ErrorResponse("Access Denied", "You do not have permission to update a project for this tenant.", 403);
                }

                // 1bb. Concurrent validation for Promoter and PMC organization existence.
                // Run database queries in parallel for better performance.
                var promoterTask = Task.Run(async () =>
                {
                    await using var context = await _dbContextFactory.CreateDbContextAsync();
                    return await context.Organizations.FirstOrDefaultAsync(o => o.Id == model.PromoterId);
                });
                var pmcTask = Task.Run(async () =>
                {
                    await using var context = await _dbContextFactory.CreateDbContextAsync();
                    return await context.Organizations.FirstOrDefaultAsync(o => o.Id == model.PMCId);
                });

                await Task.WhenAll(promoterTask, pmcTask);

                var promoter = promoterTask.Result;
                var pmc = pmcTask.Result;

                if (promoter == null)
                {
                    _logger.LogWarning("Promoter check failed. PromoterId={PromoterId} not found.", model.PromoterId);
                    return ApiResponse<object>.ErrorResponse("Promoter not found", "Promoter not found in database.", 404);
                }
                if (pmc == null)
                {
                    _logger.LogWarning("PMC check failed. PMCId={PMCId} not found.", model.PMCId);
                    return ApiResponse<object>.ErrorResponse("PMC not found", "PMC not found in database.", 404);
                }

                // 1c. Security Check
                var hasPermission = await _permission.HasProjectPermission(loggedInEmployee, id);
                if (!hasPermission)
                {
                    _logger.LogWarning("Access DENIED for user {UserId} attempting to update project {ProjectId}.", loggedInEmployee.Id, id);
                    return ApiResponse<object>.ErrorResponse("Access Denied.", "You do not have permission to modify this project.", 403);
                }

                // --- Step 2: Apply Changes and Save ---
                // Map the changes from the DTO onto the entity we just fetched from the database.
                // This only modifies the properties defined in the mapping, preventing data loss.
                _mapper.Map(model, existingProject);

                // Mark the entity as modified (if your mapping doesn't do it automatically).
                _context.Entry(existingProject).State = EntityState.Modified;

                try
                {
                    await _context.SaveChangesAsync();
                    _logger.LogInfo("Successfully updated project {ProjectId} by user {UserId}.", id, loggedInEmployee.Id);
                }
                catch (DbUpdateConcurrencyException ex)
                {
                    // --- Step 3: Handle Concurrency Conflicts ---
                    // This happens if another user modified the project after we fetched it.
                    _logger.LogError(ex, "Concurrency conflict while updating project {ProjectId} ", id);
                    return ApiResponse<object>.ErrorResponse("Conflict occurred.", "This project has been modified by someone else. Please refresh and try again.", 409);
                }

                // --- Step 4: Perform Side-Effects (Fire and Forget) ---
                // Create a DTO of the updated project to pass to background tasks.
                var projectVM = _mapper.Map<ProjectVM>(existingProject);
                projectVM.Promoter = _mapper.Map<BasicOrganizationVm>(promoter);
                projectVM.PMC = _mapper.Map<BasicOrganizationVm>(pmc);

                // 4a. Update Cache
                await UpdateCacheInBackground(existingProject);

                _ = Task.Run(async () =>
                {
                    // --- Push Notification Section ---
                    // This section attempts to send a test push notification to the user's device.
                    // It's designed to fail gracefully and handle invalid Firebase Cloud Messaging (FCM) tokens.

                    var name = $"{loggedInEmployee.FirstName} {loggedInEmployee.LastName}";

                    await _firebase.SendModifyProjectMessageAsync(existingProject, name, true, tenantId);

                });

                // --- Step 5: Return Success Response Immediately ---
                // The client gets a fast response without waiting for caching or SignalR.
                return ApiResponse<object>.SuccessResponse(projectVM, "Project updated successfully.", 200);
            }
            catch (Exception ex)
            {
                // --- Step 6: Graceful Error Handling for Unexpected Errors ---
                _logger.LogError(ex, "An unexpected error occurred while updating project {ProjectId} ", id);
                return ApiResponse<object>.ErrorResponse("An internal server error occurred.", null, 500);
            }
        }

        #endregion

        #region =================================================================== Project Allocation APIs ===================================================================

        /// <summary>
        /// Retrieves a list of employees for a specific project.
        /// This method is optimized to perform all filtering and mapping on the database server.
        /// </summary>
        /// <param name="projectId">The ID of the project.</param>
        /// <param name="includeInactive">Whether to include employees from inactive allocations.</param>
        /// <param name="tenantId">The ID of the current tenant.</param>
        /// <param name="loggedInEmployee">The current authenticated employee (used for permission checks).</param>
        /// <returns>An ApiResponse containing a list of employees or an error.</returns>
        public async Task<ApiResponse<object>> GetEmployeeByProjectIdAsync(Guid projectId, Guid? organizationId, bool includeInactive, Guid tenantId, Employee loggedInEmployee)
        {
            // --- Step 1: Input Validation ---
            if (projectId == Guid.Empty)
            {
                _logger.LogWarning("GetEmployeeByProjectID called with a null projectId.");
                // 400 Bad Request is more appropriate for invalid input than 404 Not Found.
                return ApiResponse<object>.ErrorResponse("Project ID is required.", "Invalid Input Parameter", 400);
            }

            _logger.LogInfo("Fetching employees for ProjectID: {ProjectId}, IncludeInactive: {IncludeInactive}", projectId, includeInactive);

            try
            {
                using var scope = _serviceScopeFactory.CreateScope();
                var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();

                // --- CRITICAL: Security Check  ---
                // Before fetching data, you MUST verify the user has permission to see it.
                // This is a placeholder for your actual permission logic.
                var hasProjectPermission = await _permission.HasProjectPermission(loggedInEmployee, projectId);
                var hasAllEmployeePermission = await _permission.HasPermission(PermissionsMaster.ViewAllEmployees, loggedInEmployee.Id);
                var hasviewTeamPermission = await _permission.HasPermission(PermissionsMaster.ViewTeamMembers, loggedInEmployee.Id, projectId);

                if (!(hasProjectPermission && (hasAllEmployeePermission || hasviewTeamPermission)))
                {
                    _logger.LogWarning("Access DENIED for user {UserId} on project {ProjectId}.", loggedInEmployee.Id, projectId);
                    return ApiResponse<object>.ErrorResponse("Access Denied.", "You do not have permission to view this project's team.", 403);
                }

                // --- Step 2: Build a Single, Efficient IQueryable ---
                // We start with the base query and conditionally add filters before executing it.
                // This avoids code duplication and is highly performant.
                var employeeQuery = _context.ProjectAllocations
                    .Include(pa => pa.Employee)
                    .Where(pa => pa.ProjectId == projectId && pa.TenantId == tenantId);

                // Conditionally apply the filter for active allocations.
                if (!includeInactive)
                {
                    employeeQuery = employeeQuery.Where(pa => pa.IsActive);
                }

                // Conditionally apply the filter for organization ID.
                if (organizationId.HasValue)
                {
                    employeeQuery = employeeQuery.Where(pa => pa.Employee != null && pa.Employee.OrganizationId == organizationId.Value);
                }

                // --- Step 3: Project Directly to the ViewModel on the Database Server ---
                // This is the most significant performance optimization.
                // Instead of fetching full Employee entities, we select only the data needed for the EmployeeVM.
                // AutoMapper's ProjectTo is perfect for this, as it translates the mapping configuration into an efficient SQL SELECT statement.

                var projectAllocations = await employeeQuery
                    .Where(pa => pa.Employee != null) // Safety check for data integrity
                    .ToListAsync();

                var resultVM = projectAllocations.Select(pa => _mapper.Map<EmployeeVM>(pa.Employee)).ToList();

                _logger.LogInfo("Successfully fetched {EmployeeCount} employees for project {ProjectId}.", resultVM.Count, projectId);

                // Note: The original mapping loop is now completely gone, replaced by the single efficient query above.

                return ApiResponse<object>.SuccessResponse(resultVM, "Successfully fetched the list of employees for the selected project.", 200);
            }
            catch (Exception ex)
            {
                // --- Step 4: Graceful Error Handling ---
                _logger.LogError(ex, "An error occurred while fetching employees for project {ProjectId}. ", projectId);
                return ApiResponse<object>.ErrorResponse("An internal server error occurred.", "Database Query Failed", 500);
            }
        }

        /// <summary>
        /// Retrieves project allocation details for a specific project.
        /// This method is optimized for performance and includes security checks.
        /// </summary>
        /// <param name="projectId">The ID of the project.</param>
        /// <param name="tenantId">The ID of the current tenant.</param>
        /// <param name="loggedInEmployee">The current authenticated employee for permission checks.</param>
        /// <returns>An ApiResponse containing allocation details or an appropriate error.</returns>
        public async Task<ApiResponse<object>> GetProjectAllocationAsync(Guid projectId, Guid? organizationId, Guid? serviceId, bool includeInactive, Guid tenantId, Employee loggedInEmployee)
        {
            // --- Step 1: Input Validation ---
            if (projectId == Guid.Empty)
            {
                _logger.LogWarning("GetProjectAllocation called with a null projectId.");
                return ApiResponse<object>.ErrorResponse("Project ID is required.", "Invalid Input Parameter", 400);
            }

            _logger.LogInfo("Fetching allocations for ProjectID: {ProjectId} for user {UserId}", projectId, loggedInEmployee.Id);

            try
            {
                using var scope = _serviceScopeFactory.CreateScope();
                var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();

                // --- Step 2: Security and Existence Checks ---
                // Before fetching data, you MUST verify the user has permission to see it.
                // This is a placeholder for your actual permission logic.
                var hasPermission = await _permission.HasProjectPermission(loggedInEmployee, projectId);
                if (!hasPermission)
                {
                    _logger.LogWarning("Access DENIED for user {UserId} on project {ProjectId}.", loggedInEmployee.Id, projectId);
                    return ApiResponse<object>.ErrorResponse("Access Denied.", "You do not have permission to view this project's team.", 403);
                }

                // --- Step 3: Execute a Single, Optimized Database Query ---
                // This query projects directly to a new object on the database server, which is highly efficient.
                var projectAllocationQuery = _context.ProjectAllocations
                    .Include(pa => pa.Employee)
                        .ThenInclude(e => e!.JobRole)
                    .Include(pa => pa.Employee)
                        .ThenInclude(e => e!.Organization)
                    .Include(pa => pa.Service)
                    .Where(pa => pa.ProjectId == projectId && pa.TenantId == tenantId && pa.Service != null);

                // Conditionally apply the filter for active allocations.
                if (!includeInactive)
                {
                    projectAllocationQuery = projectAllocationQuery.Where(pa => pa.IsActive);
                }

                // Conditionally apply the filter for organization ID.
                if (organizationId.HasValue)
                {
                    projectAllocationQuery = projectAllocationQuery
                        .Where(pa => pa.Employee != null && pa.Employee.OrganizationId == organizationId.Value && pa.Employee.Organization != null);
                }
                // Conditionally apply the filter for service ID.
                if (serviceId.HasValue)
                {
                    projectAllocationQuery = projectAllocationQuery
                        .Where(pa => pa.Employee != null && pa.ServiceId == serviceId.Value);
                }

                var allocations = await projectAllocationQuery
                    .Select(pa => new
                    {
                        // Fields from ProjectAllocation
                        ID = pa.Id,
                        pa.EmployeeId,
                        pa.ProjectId,
                        pa.AllocationDate,
                        pa.ReAllocationDate,
                        pa.IsActive,

                        // Fields from the joined Employee table (no null checks needed due to the 'Where' clause)
                        FirstName = pa.Employee!.FirstName,
                        LastName = pa.Employee.LastName,
                        MiddleName = pa.Employee.MiddleName,

                        OrganizationName = pa.Employee.Organization!.Name,

                        ServiceName = pa.Service!.Name,

                        // Simplified JobRoleId logic: Use the allocation's role if it exists, otherwise fall back to the employee's default role.
                        JobRoleId = pa.JobRoleId ?? pa.Employee.JobRoleId
                    })
                    .ToListAsync();

                _logger.LogInfo("Successfully fetched {AllocationCount} allocations for project {ProjectId}.", allocations.Count, projectId);

                return ApiResponse<object>.SuccessResponse(allocations, "Project allocations retrieved successfully.", 200);
            }
            catch (Exception ex)
            {
                // --- Step 4: Graceful Error Handling ---
                // Log the full exception for debugging, but return a generic, safe error message.
                _logger.LogError(ex, "An error occurred while fetching allocations for project {ProjectId}.", projectId);
                return ApiResponse<object>.ErrorResponse("An internal server error occurred.", "Database query failed.", 500);
            }
        }

        /// <summary>
        /// Manages project allocations for a list of employees, either adding new allocations or deactivating existing ones.
        /// This method is optimized to perform all database operations in a single transaction.
        /// </summary>
        /// <param name="allocationsDto">The list of allocation changes to process.</param>
        /// <param name="tenantId">The ID of the current tenant.</param>
        /// <param name="loggedInEmployee">The current authenticated employee for permission checks.</param>
        /// <returns>An ApiResponse containing the list of processed allocations.</returns>
        public async Task<ApiResponse<List<ProjectAllocationVM>>> ManageAllocationAsync(List<ProjectAllocationDot> allocationsDto, Guid tenantId, Employee loggedInEmployee)
        {
            using var scope = _serviceScopeFactory.CreateScope();
            var _firebase = scope.ServiceProvider.GetRequiredService<IFirebaseService>();

            // --- Step 1: Input Validation ---
            if (allocationsDto == null || !allocationsDto.Any())
            {
                return ApiResponse<List<ProjectAllocationVM>>.ErrorResponse("Invalid details.", "Allocation details list cannot be null or empty.", 400);
            }

            _logger.LogInfo("Starting to manage {AllocationCount} allocations for user {UserId}.", allocationsDto.Count, loggedInEmployee.Id);

            var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();

            // --- (Placeholder) Security Check ---
            // In a real application, you would check if the loggedInEmployee has permission
            // to manage allocations for ALL projects involved in this batch.
            var projectIdsInBatch = allocationsDto.Select(a => a.ProjectId).Distinct().ToList();
            var projectId = projectIdsInBatch.FirstOrDefault();
            var hasPermission = await _permission.HasPermission(PermissionsMaster.ManageTeam, loggedInEmployee.Id, projectId);
            if (!hasPermission)
            {
                _logger.LogWarning("Access DENIED for user {UserId} trying to manage allocations for projects.", loggedInEmployee.Id);
                return ApiResponse<List<ProjectAllocationVM>>.ErrorResponse("Access Denied.", "You do not have permission to manage one or more projects in this request.", 403);
            }

            // --- Step 2: Fetch all relevant existing data in ONE database call ---
            var employeeProjectPairs = allocationsDto.Select(a => new { a.EmployeeId, a.ProjectId }).ToList();
            List<Guid> employeeIds = allocationsDto.Select(a => a.EmployeeId).Distinct().ToList();

            // Fetch all currently active allocations for the employees and projects in this batch.
            // We use a dictionary for fast O(1) lookups inside the loop.
            var existingAllocations = await _context.ProjectAllocations
                .Where(pa => pa.TenantId == tenantId &&
                             employeeIds.Contains(pa.EmployeeId) &&
                             pa.ReAllocationDate == null)
                .ToDictionaryAsync(pa => (pa.EmployeeId, pa.ProjectId));

            var processedAllocations = new List<ProjectAllocation>();

            // --- Step 3: Process logic IN MEMORY ---
            foreach (var dto in allocationsDto)
            {
                var key = (dto.EmployeeId, dto.ProjectId);
                existingAllocations.TryGetValue(key, out var existingAllocation);

                if (dto.Status == false) // User wants to DEACTIVATE the allocation
                {
                    if (existingAllocation != null)
                    {
                        // Mark the existing allocation for deactivation
                        existingAllocation.ReAllocationDate = DateTime.UtcNow; // Use UtcNow for servers
                        existingAllocation.IsActive = false;
                        _context.ProjectAllocations.Update(existingAllocation);
                        processedAllocations.Add(existingAllocation);
                    }
                    // If it doesn't exist, we do nothing. The desired state is "not allocated".
                }
                else // User wants to ACTIVATE the allocation
                {
                    if (existingAllocation == null)
                    {
                        // Create a new allocation because one doesn't exist
                        var newAllocation = _mapper.Map<ProjectAllocation>(dto);
                        newAllocation.TenantId = tenantId;
                        newAllocation.AllocationDate = DateTime.UtcNow;
                        newAllocation.IsActive = true;
                        _context.ProjectAllocations.Add(newAllocation);
                        processedAllocations.Add(newAllocation);
                    }
                    // If it already exists and is active, we do nothing. The state is already correct.
                }
                try
                {
                    await _cache.ClearAllProjectIds(dto.EmployeeId, tenantId);
                    _logger.LogInfo("Successfully completed cache invalidation for employee {EmployeeId}.", dto.EmployeeId);
                }
                catch (Exception ex)
                {
                    // Log the error but don't fail the entire request, as the primary DB operation succeeded.
                    _logger.LogError(ex, "Cache invalidation failed for employees after a successful database update.");
                }
            }

            try
            {
                // --- Step 4: Save all changes in a SINGLE TRANSACTION ---
                // All Adds and Updates are sent to the database in one batch.
                // If any part fails, the entire transaction is rolled back.
                await _context.SaveChangesAsync();
                _logger.LogInfo("Successfully saved {ChangeCount} allocation changes to the database.", processedAllocations.Count);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Failed to save allocation changes to the database.");
                return ApiResponse<List<ProjectAllocationVM>>.ErrorResponse("Database Error.", "An error occurred while saving the changes.", 500);
            }


            // --- Step 5: Map results and return success ---
            var resultVm = _mapper.Map<List<ProjectAllocationVM>>(processedAllocations);
            _ = Task.Run(async () =>
            {
                // --- Push Notification Section ---
                // This section attempts to send a test push notification to the user's device.
                // It's designed to fail gracefully and handle invalid Firebase Cloud Messaging (FCM) tokens.

                var name = $"{loggedInEmployee.FirstName} {loggedInEmployee.LastName}";

                await _firebase.SendProjectAllocationMessageAsync(processedAllocations, name, tenantId);

            });
            return ApiResponse<List<ProjectAllocationVM>>.SuccessResponse(resultVm, "Allocations managed successfully.", 200);
        }

        /// <summary>
        /// Retrieves a list of active projects assigned to a specific employee.
        /// </summary>
        /// <param name="employeeId">The ID of the employee whose projects are being requested.</param>
        /// <param name="tenantId">The ID of the current tenant.</param>
        /// <param name="loggedInEmployee">The current authenticated employee for permission checks.</param>
        /// <returns>An ApiResponse containing a list of basic project details or an error.</returns>
        public async Task<ApiResponse<object>> GetProjectsByEmployeeAsync(Guid employeeId, Guid tenantId, Employee loggedInEmployee)
        {
            // --- Step 1: Input Validation ---
            if (employeeId == Guid.Empty)
            {
                return ApiResponse<object>.ErrorResponse("Invalid details.", "A valid employee ID is required.", 400);
            }

            _logger.LogInfo("Fetching projects for Employee {EmployeeId} by User {UserId}", employeeId, loggedInEmployee.Id);

            try
            {
                using var scope = _serviceScopeFactory.CreateScope();
                var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();

                // --- Step 2: Clarified Security Check ---
                // The permission should be about viewing another employee's assignments, not a generic "Manage Team".
                // This is a placeholder for your actual, more specific permission logic.
                // It should also handle the case where a user is requesting their own projects (employeeId == loggedInEmployee.Id).
                var hasPermission = await _permission.HasPermission(PermissionsMaster.ViewProject, loggedInEmployee.Id);
                var projectIds = await GetMyProjects(tenantId, loggedInEmployee);
                if (!hasPermission)
                {
                    _logger.LogWarning("Access DENIED for user {UserId} trying to view projects for employee {TargetEmployeeId}.", loggedInEmployee.Id, employeeId);
                    return ApiResponse<object>.ErrorResponse("Access Denied.", "You do not have permission to view this employee's projects.", 403);
                }

                // --- Step 3: Execute a Single, Highly Efficient Database Query ---
                // This query projects directly to the ViewModel on the database server.
                var projects = await _context.ProjectAllocations
                    // 1. Filter the linking table down to the relevant records.
                    .Where(pa =>
                        pa.TenantId == tenantId &&
                        pa.EmployeeId == employeeId && // Target the specified employee
                        pa.IsActive &&                 // Only active assignments
                        projectIds.Contains(pa.ProjectId) &&
                        pa.Project != null)            // Safety check for data integrity

                    // 2. Navigate to the Project entity.
                    .Select(pa => pa.Project)

                    // 3. Ensure the final result set is unique (in case of multiple active allocations to the same project).
                    .Distinct()

                    // 4. Project directly to the ViewModel using AutoMapper's IQueryable Extensions.
                    // This generates an efficient SQL "SELECT Id, Name, Code FROM..." statement.
                    .ProjectTo<ProjectInfoVM>(_mapper.ConfigurationProvider)

                    // 5. Execute the query.
                    .ToListAsync();

                _logger.LogInfo("Successfully retrieved {ProjectCount} projects for employee {EmployeeId}.", projects.Count, employeeId);

                // The original check for an empty list is still good practice.
                if (!projects.Any())
                {
                    return ApiResponse<object>.SuccessResponse(new List<ProjectInfoVM>(), "No active projects found for this employee.", 200);
                }

                return ApiResponse<object>.SuccessResponse(projects, "Projects retrieved successfully.", 200);
            }
            catch (Exception ex)
            {
                // --- Step 4: Graceful Error Handling ---
                _logger.LogError(ex, "An error occurred while fetching projects for employee {EmployeeId}.", employeeId);
                return ApiResponse<object>.ErrorResponse("An internal server error occurred.", "Database query failed.", 500);
            }
        }

        /// <summary>
        /// Manages project assignments for a single employee, processing a batch of projects to activate or deactivate.
        /// This method is optimized to perform all database operations in a single, atomic transaction.
        /// </summary>
        /// <param name="allocationsDto">A list of projects to assign or un-assign.</param>
        /// <param name="employeeId">The ID of the employee whose assignments are being managed.</param>
        /// <param name="tenantId">The ID of the current tenant.</param>
        /// <param name="loggedInEmployee">The current authenticated employee for permission checks.</param>
        /// <returns>An ApiResponse containing the list of processed allocations.</returns>
        public async Task<ApiResponse<List<ProjectAllocationVM>>> AssigneProjectsToEmployeeAsync(List<ProjectsAllocationDto> allocationsDto, Guid employeeId, Guid tenantId, Employee loggedInEmployee)
        {
            using var scope = _serviceScopeFactory.CreateScope();
            var _firebase = scope.ServiceProvider.GetRequiredService<IFirebaseService>();

            // --- Step 1: Input Validation ---
            if (allocationsDto == null || !allocationsDto.Any() || employeeId == Guid.Empty)
            {
                return ApiResponse<List<ProjectAllocationVM>>.ErrorResponse("Invalid details.", "A valid employee ID and a list of projects are required.", 400);
            }

            _logger.LogInfo("Starting to manage {AllocationCount} project assignments for Employee {EmployeeId}.", allocationsDto.Count, employeeId);

            var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();

            // --- (Placeholder) Security Check ---
            // You MUST verify that the loggedInEmployee has permission to modify the assignments for the target employeeId.
            foreach (var allocation in allocationsDto)
            {
                if (!await _permission.HasPermission(PermissionsMaster.ManageTeam, loggedInEmployee.Id, allocation.ProjectId))
                {
                    _logger.LogWarning("Access DENIED for user {UserId} trying to manage assignments for employee {TargetEmployeeId}.", loggedInEmployee.Id, employeeId);
                    return ApiResponse<List<ProjectAllocationVM>>.ErrorResponse("Access Denied.", "You do not have permission to manage this employee's assignments.", 403);
                }
            }


            // --- Step 2: Fetch all relevant existing data in ONE database call ---
            var projectIdsInDto = allocationsDto.Select(p => p.ProjectId).ToList();

            // Fetch all currently active allocations for this employee for the projects in the request.
            // We use a dictionary keyed by ProjectId for fast O(1) lookups inside the loop.
            var existingActiveAllocations = await _context.ProjectAllocations
                .Where(pa => pa.TenantId == tenantId &&
                             pa.EmployeeId == employeeId &&
                             projectIdsInDto.Contains(pa.ProjectId) &&
                             pa.ReAllocationDate == null) // Only fetch active ones
                .ToDictionaryAsync(pa => pa.ProjectId);

            var processedAllocations = new List<ProjectAllocation>();

            // --- Step 3: Process all logic IN MEMORY, tracking changes ---
            foreach (var dto in allocationsDto)
            {
                existingActiveAllocations.TryGetValue(dto.ProjectId, out var existingAllocation);

                if (dto.Status == false) // DEACTIVATE this project assignment
                {
                    if (existingAllocation != null)
                    {
                        // Correct Update Pattern: Modify the fetched entity directly.
                        existingAllocation.ReAllocationDate = DateTime.UtcNow; // Use UTC for servers
                        existingAllocation.IsActive = false;
                        _context.ProjectAllocations.Update(existingAllocation);
                        processedAllocations.Add(existingAllocation);
                    }
                    // If it's not in our dictionary, it's already inactive. Do nothing.
                }
                else // ACTIVATE this project assignment
                {
                    if (existingAllocation == null)
                    {
                        // Create a new allocation because an active one doesn't exist.
                        var newAllocation = _mapper.Map<ProjectAllocation>(dto);
                        newAllocation.EmployeeId = employeeId;
                        newAllocation.TenantId = tenantId;
                        newAllocation.AllocationDate = DateTime.UtcNow;
                        newAllocation.IsActive = true;
                        _context.ProjectAllocations.Add(newAllocation);
                        processedAllocations.Add(newAllocation);
                    }
                    // If it already exists in our dictionary, it's already active. Do nothing.
                }
            }

            try
            {
                // --- Step 4: Save all Adds and Updates in a SINGLE ATOMIC TRANSACTION ---
                if (processedAllocations.Any())
                {
                    await _context.SaveChangesAsync();
                    _logger.LogInfo("Successfully saved {ChangeCount} assignment changes for employee {EmployeeId}.", processedAllocations.Count, employeeId);
                }
            }
            catch (DbUpdateException ex)
            {
                _logger.LogError(ex, "Failed to save assignment changes for employee {EmployeeId}.", employeeId);
                return ApiResponse<List<ProjectAllocationVM>>.ErrorResponse("Database Error.", "An error occurred while saving the changes.", 500);
            }

            // --- Step 5: Invalidate Cache ONCE after successful save ---
            try
            {
                await _cache.ClearAllProjectIds(employeeId, tenantId);
                _logger.LogInfo("Successfully queued cache invalidation for employee {EmployeeId}.", employeeId);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Background cache invalidation failed for employee {EmployeeId}", employeeId);
            }

            // --- Step 6: Map results using AutoMapper and return success ---
            var resultVm = _mapper.Map<List<ProjectAllocationVM>>(processedAllocations);
            _ = Task.Run(async () =>
            {
                // --- Push Notification Section ---
                // This section attempts to send a test push notification to the user's device.
                // It's designed to fail gracefully and handle invalid Firebase Cloud Messaging (FCM) tokens.

                var name = $"{loggedInEmployee.FirstName} {loggedInEmployee.LastName}";

                await _firebase.SendProjectAllocationMessageAsync(processedAllocations, name, tenantId);

            });
            return ApiResponse<List<ProjectAllocationVM>>.SuccessResponse(resultVm, "Assignments managed successfully.", 200);
        }

        public async Task<ApiResponse<object>> GetProjectByEmployeeBasicAsync(Guid employeeId, Guid tenantId, Employee loggedInEmployee)
        {
            // Log the start of the method execution with key input parameters
            _logger.LogInfo("Fetching projects for EmployeeId: {EmployeeId}, TenantId: {TenantId} by User: {UserId}",
                employeeId, tenantId, loggedInEmployee.Id);

            try
            {
                // Retrieve project allocations linked to the specified employee and tenant
                var projectAllocation = await _context.ProjectAllocations
                    .AsNoTracking() // Optimization: no tracking since entities are not updated
                    .Include(pa => pa.Project) // Include related Project data
                    .Include(pa => pa.Employee).ThenInclude(e => e!.JobRole) // Include related Employee and their JobRole
                    .Where(pa => pa.EmployeeId == employeeId
                                 && pa.TenantId == tenantId
                                 && pa.Project != null
                                 && pa.Employee != null)
                    .Select(pa => new
                    {
                        ProjectName = pa.Project!.Name,
                        ProjectShortName = pa.Project.ShortName,
                        AssignedDate = pa.AllocationDate,
                        RemovedDate = pa.ReAllocationDate,
                        Designation = pa.Employee!.JobRole!.Name,
                        DesignationId = pa.JobRoleId
                    })
                    .ToListAsync();

                var designationIds = projectAllocation.Select(pa => pa.DesignationId).ToList();

                var designations = await _context.JobRoles.Where(jr => designationIds.Contains(jr.Id)).ToListAsync();

                var response = projectAllocation.Select(pa =>
                {
                    var designation = designations.FirstOrDefault(jr => jr.Id == pa.DesignationId);
                    return new ProjectHisteryVM
                    {
                        ProjectName = pa.ProjectName,
                        ProjectShortName = pa.ProjectShortName,
                        AssignedDate = pa.AssignedDate,
                        RemovedDate = pa.RemovedDate,
                        Designation = designation?.Name
                    };
                }).ToList();

                // Log successful retrieval including count of records
                _logger.LogInfo("Successfully fetched {Count} projects for EmployeeId: {EmployeeId}",
                    projectAllocation.Count, employeeId);

                return ApiResponse<object>.SuccessResponse(
                    response,
                    $"{response.Count} project assignments fetched for employee.",
                    200);
            }
            catch (Exception ex)
            {
                // Log the exception with stack trace for debugging
                _logger.LogError(ex, "Error occurred while fetching projects for EmployeeId: {EmployeeId}, TenantId: {TenantId}",
                    employeeId, tenantId);

                return ApiResponse<object>.ErrorResponse(
                    "An error occurred while fetching project assignments.",
                    500);
            }
        }


        #endregion

        #region =================================================================== Project InfraStructure Get APIs ===================================================================

        /// <summary>
        /// Retrieves the full infrastructure hierarchy (Buildings, Floors, Work Areas) for a project,
        /// including aggregated work summaries.
        /// </summary>
        public async Task<ApiResponse<object>> GetInfraDetailsAsync(Guid projectId, Guid? serviceId, Guid tenantId, Employee loggedInEmployee)
        {
            _logger.LogInfo("GetInfraDetails called for ProjectId: {ProjectId}", projectId);

            using var scope = _serviceScopeFactory.CreateScope();
            var _generalHelper = scope.ServiceProvider.GetRequiredService<GeneralHelper>();

            try
            {
                var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();
                // --- Step 1: Run independent permission checks in PARALLEL ---
                var projectPermissionTask = _permission.HasProjectPermission(loggedInEmployee, projectId);
                var viewInfraPermissionTask = Task.Run(async () =>
                {
                    using var newScope = _serviceScopeFactory.CreateScope();
                    var permission = newScope.ServiceProvider.GetRequiredService<PermissionServices>();
                    return await permission.HasPermission(PermissionsMaster.ViewProjectInfra, loggedInEmployee.Id, projectId);
                });
                var manageInfraPermissionTask = Task.Run(async () =>
                {
                    using var newScope = _serviceScopeFactory.CreateScope();
                    var permission = newScope.ServiceProvider.GetRequiredService<PermissionServices>();
                    return await permission.HasPermission(PermissionsMaster.ManageProjectInfra, loggedInEmployee.Id, projectId);
                });

                await Task.WhenAll(projectPermissionTask, viewInfraPermissionTask, manageInfraPermissionTask);

                var hasProjectPermission = projectPermissionTask.Result;
                var hasViewInfraPermission = viewInfraPermissionTask.Result;
                var hasManageInfraPermission = manageInfraPermissionTask.Result;

                if (!hasProjectPermission)
                {
                    _logger.LogWarning("Project access denied for EmployeeId: {EmployeeId} on ProjectId: {ProjectId}", loggedInEmployee.Id, projectId);
                    return ApiResponse<object>.ErrorResponse("Access denied", "You don't have access to this project", 403);
                }
                if (!hasViewInfraPermission && !hasManageInfraPermission)
                {
                    _logger.LogWarning("ViewInfra permission denied for EmployeeId: {EmployeeId}", loggedInEmployee.Id);
                    return ApiResponse<object>.ErrorResponse("Access denied", "You don't have access to view this project's infrastructure", 403);
                }

                // --- Step 2: Cache-First Strategy ---
                var cachedResult = await _cache.GetBuildingInfra(projectId);
                if (cachedResult != null)
                {
                    _logger.LogInfo("Cache HIT for infra details for ProjectId: {ProjectId}", projectId);
                }

                _logger.LogInfo("Cache MISS for infra details for ProjectId: {ProjectId}. Fetching from database.", projectId);

                // --- Step 3: Fetch all required data from the database ---
                if (cachedResult == null)
                {
                    cachedResult = await _generalHelper.GetProjectInfraFromDB(projectId);
                }
                // --- Step 5: Proactively update the cache ---
                //await _cache.SetBuildingInfra(projectId, buildingMongoList);

                if (serviceId.HasValue)
                {
                    var workAreaIds = cachedResult
                        .SelectMany(b => b.Floors)
                        .SelectMany(f => f.WorkAreas)
                        .Select(w => Guid.Parse(w.Id))
                        .ToList();

                    var workItems = await _context.WorkItems.Where(wi => workAreaIds.Contains(wi.WorkAreaId)
                            && wi.ActivityMaster != null
                            && wi.ActivityMaster.ActivityGroup != null
                            && wi.ActivityMaster.ActivityGroup.ServiceId == serviceId)
                        .GroupBy(wi => wi.WorkAreaId)
                        .Select(g => new
                        {
                            WorkAreaId = g.Key,
                            PlannedWork = g.Sum(wi => wi.PlannedWork),
                            CompletedWork = g.Sum(wi => wi.CompletedWork)
                        })
                        .ToListAsync();

                    cachedResult = cachedResult.Select(b =>
                    {
                        double buildingPlanned = 0, buildingCompleted = 0;
                        var floors = b.Floors.Select(f =>
                        {
                            double floorPlanned = 0, floorCompleted = 0;
                            var workArea = f.WorkAreas.Select(wa =>
                            {
                                var workItem = workItems.FirstOrDefault(wi => wi.WorkAreaId == Guid.Parse(wa.Id));
                                wa.PlannedWork = workItem?.PlannedWork ?? 0;
                                wa.CompletedWork = workItem?.CompletedWork ?? 0;

                                floorPlanned += workItem?.PlannedWork ?? 0;
                                floorCompleted += workItem?.CompletedWork ?? 0;

                                return wa;
                            }).ToList();

                            f.PlannedWork = floorPlanned;
                            f.CompletedWork = floorCompleted;

                            buildingPlanned += floorPlanned;
                            buildingCompleted += floorCompleted;

                            return f;
                        }).ToList();
                        b.PlannedWork = buildingPlanned;
                        b.CompletedWork = buildingCompleted;
                        return b;
                    }).ToList();

                }

                _logger.LogInfo("Infra details fetched successfully for ProjectId: {ProjectId}, Buildings: {Count}", projectId, cachedResult.Count);
                return ApiResponse<object>.SuccessResponse(cachedResult, "Infra details fetched successfully", 200);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "An error occurred while fetching infra details for ProjectId: {ProjectId}", projectId);
                return ApiResponse<object>.ErrorResponse("An internal server error occurred.", "An error occurred while processing your request.", 500);
            }
        }

        /// <summary>
        /// Retrieves a list of work items for a specific work area, ensuring the user has appropriate permissions.
        /// </summary>
        /// <param name="workAreaId">The ID of the work area.</param>
        /// <param name="tenantId">The ID of the current tenant.</param>
        /// <param name="loggedInEmployee">The current authenticated employee for permission checks.</param>
        /// <returns>An ApiResponse containing a list of work items or an error.</returns>
        public async Task<ApiResponse<object>> GetWorkItemsAsync(Guid workAreaId, Guid? serviceId, Guid tenantId, Employee loggedInEmployee)
        {
            _logger.LogInfo("GetWorkItems called for WorkAreaId: {WorkAreaId} by User: {UserId}", workAreaId, loggedInEmployee.Id);

            using var scope = _serviceScopeFactory.CreateScope();
            var _generalHelper = scope.ServiceProvider.GetRequiredService<GeneralHelper>();

            try
            {
                var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();

                var projectId = await _context.WorkAreas
                   .Where(wa => wa.Id == workAreaId && wa.TenantId == tenantId && wa.Floor != null && wa.Floor.Building != null)
                   .Select(wa => wa.Floor!.Building!.ProjectId)
                   .FirstOrDefaultAsync();

                if (projectId == Guid.Empty)
                {
                    _logger.LogWarning("Work Area not found for WorkAreaId: {WorkAreaId}", workAreaId);
                    return ApiResponse<object>.ErrorResponse("Not Found", $"Work Area with ID {workAreaId} not found.", 404);
                }

                var project = await _context.Projects.FirstOrDefaultAsync(p => p.Id == projectId && p.TenantId == tenantId);
                if (project == null)
                {
                    return ApiResponse<object>.ErrorResponse("Project not found", "Project not found in database", 404);
                }

                var hasProjectAccessTask = Task.Run(async () =>
                {
                    using var taskScope = _serviceScopeFactory.CreateScope();
                    var permission = taskScope.ServiceProvider.GetRequiredService<PermissionServices>();
                    return await permission.HasProjectPermission(loggedInEmployee, projectId);
                });
                var hasGenericViewInfraPermissionTask = Task.Run(async () =>
                {
                    using var taskScope = _serviceScopeFactory.CreateScope();
                    var permission = taskScope.ServiceProvider.GetRequiredService<PermissionServices>();
                    return await permission.HasPermission(PermissionsMaster.ViewProjectInfra, loggedInEmployee.Id, projectId);
                });

                await Task.WhenAll(hasProjectAccessTask, hasGenericViewInfraPermissionTask);

                var hasProjectAccess = hasProjectAccessTask.Result;
                var hasGenericViewInfraPermission = hasGenericViewInfraPermissionTask.Result;

                if (!hasProjectAccess || !hasGenericViewInfraPermission)
                {
                    _logger.LogWarning("Access DENIED for user {UserId} on WorkAreaId {WorkAreaId}.", loggedInEmployee.Id, workAreaId);
                    return ApiResponse<object>.ErrorResponse("Access Denied", "You do not have sufficient permissions to view these work items.", 403);
                }

                List<Guid> serviceIds = new List<Guid>();
                if (!serviceId.HasValue)
                {
                    if (project.PromoterId == loggedInEmployee.OrganizationId && project.PMCId == loggedInEmployee.OrganizationId)
                    {
                        var projectServices = await _context.ProjectServiceMappings
                            .Include(ps => ps.Service)
                            .Where(ps => ps.ProjectId == projectId && ps.Service != null && ps.TenantId == tenantId && ps.IsActive)
                            .ToListAsync();
                        serviceIds = projectServices.Select(ps => ps.ServiceId).Distinct().ToList();
                    }
                    else
                    {
                        var orgProjectMapping = await _context.ProjectOrgMappings
                            .Include(po => po.ProjectService)
                                .ThenInclude(ps => ps!.Service)
                            .Where(po => po.OrganizationId == loggedInEmployee.OrganizationId && po.ProjectService != null
                            && po.ProjectService.IsActive && po.ProjectService.ProjectId == projectId && po.ProjectService.Service != null)
                            .ToListAsync();

                        serviceIds = orgProjectMapping.Select(po => po.ProjectService!.ServiceId).Distinct().ToList();
                    }
                }
                else
                {
                    serviceIds.Add(serviceId.Value);
                }

                // --- Step 1: Cache-First Strategy ---
                var cachedWorkItems = await _cache.GetWorkItemDetailsByWorkArea(workAreaId, serviceIds);
                if (cachedWorkItems != null)
                {
                    _logger.LogInfo("Cache HIT for WorkAreaId: {WorkAreaId}. Returning {Count} items from cache.", workAreaId, cachedWorkItems.Count);
                    return ApiResponse<object>.SuccessResponse(cachedWorkItems, $"{cachedWorkItems.Count} tasks retrieved successfully from cache.", 200);
                }

                _logger.LogInfo("Cache MISS for WorkAreaId: {WorkAreaId}. Fetching from database.", workAreaId);

                // --- Step 3: Fetch Full Entities for Caching and Mapping ---
                var workItemVMs = await _generalHelper.GetWorkItemsListFromDB(workAreaId);

                // --- Step 5: Proactively Update the Cache with the Correct Object Type ---
                // We now pass the 'workItemsFromDb' list, which is the required List<WorkItem>.

                try
                {
                    await _cache.ManageWorkItemDetailsByVM(workItemVMs);
                    _logger.LogInfo("Successfully queued cache update for WorkAreaId: {WorkAreaId}", workAreaId);
                }
                catch (Exception ex)
                {
                    _logger.LogError(ex, "Background cache update failed for WorkAreaId: {WorkAreaId}", workAreaId);
                }

                var stringServiceIds = serviceIds.Select(s => s.ToString()).ToList();
                workItemVMs = workItemVMs.Where(wi => stringServiceIds.Contains(wi.ActivityMaster!.ActivityGroupMaster!.Service!.Id)).ToList();

                _logger.LogInfo("{Count} work items fetched successfully for WorkAreaId: {WorkAreaId}", workItemVMs.Count, workAreaId);
                return ApiResponse<object>.SuccessResponse(workItemVMs, $"{workItemVMs.Count} tasks fetched successfully.", 200);
            }
            catch (Exception ex)
            {
                // --- Step 6: Graceful Error Handling ---
                _logger.LogError(ex, "An unexpected error occurred while getting work items for WorkAreaId: {WorkAreaId}", workAreaId);
                return ApiResponse<object>.ErrorResponse("An internal server error occurred.", null, 500);
            }
        }

        /// <summary>
        /// Retrieves tasks assigned to a specific employee within a date range for a tenant.
        /// </summary>
        /// <param name="employeeId">The ID of the employee to filter tasks.</param>
        /// <param name="fromDate">The start date to filter task assignments.</param>
        /// <param name="toDate">The end date to filter task assignments.</param>
        /// <param name="tenantId">The tenant ID to filter tasks.</param>
        /// <param name="loggedInEmployee">The employee requesting the data (for authorization/logging).</param>
        /// <returns>An ApiResponse containing the task details.</returns>
        public async Task<ApiResponse<object>> GetTasksByEmployeeAsync(Guid employeeId, DateTime fromDate, DateTime toDate, Guid tenantId, Employee loggedInEmployee)
        {
            _logger.LogInfo("Fetching tasks for EmployeeId: {EmployeeId} from {FromDate} to {ToDate} for TenantId: {TenantId}",
                employeeId, fromDate, toDate, tenantId);

            try
            {
                // Query TaskMembers with related necessary fields in one projection to minimize DB calls and data size
                var taskData = await _context.TaskMembers
                    .Where(tm => tm.EmployeeId == employeeId &&
                                 tm.TenantId == tenantId &&
                                 tm.TaskAllocation != null &&
                                 tm.TaskAllocation.AssignmentDate.Date >= fromDate.Date &&
                                 tm.TaskAllocation.AssignmentDate.Date <= toDate.Date)
                    .Select(tm => new
                    {
                        AssignmentDate = tm.TaskAllocation!.AssignmentDate,
                        PlannedTask = tm.TaskAllocation.PlannedTask,
                        CompletedTask = tm.TaskAllocation.CompletedTask,
                        ProjectId = tm.TaskAllocation.WorkItem!.WorkArea!.Floor!.Building!.ProjectId,
                        BuildingName = tm.TaskAllocation.WorkItem.WorkArea.Floor.Building!.Name,
                        FloorName = tm.TaskAllocation.WorkItem.WorkArea.Floor.FloorName,
                        AreaName = tm.TaskAllocation.WorkItem.WorkArea.AreaName,
                        ActivityName = tm.TaskAllocation.WorkItem.ActivityMaster!.ActivityName,
                        ActivityUnit = tm.TaskAllocation.WorkItem.ActivityMaster.UnitOfMeasurement
                    })
                    .OrderByDescending(t => t.AssignmentDate)
                    .ToListAsync();

                _logger.LogInfo("Retrieved {TaskCount} tasks for EmployeeId: {EmployeeId}", taskData.Count, employeeId);

                // Extract distinct project IDs to fetch project details efficiently
                var distinctProjectIds = taskData.Select(t => t.ProjectId).Distinct().ToList();

                var projects = await _context.Projects
                    .Where(p => distinctProjectIds.Contains(p.Id))
                    .Select(p => new { p.Id, p.Name })
                    .ToListAsync();

                // Prepare the response
                var response = taskData.Select(t =>
                {
                    var project = projects.FirstOrDefault(p => p.Id == t.ProjectId);

                    return new
                    {
                        ProjectName = project?.Name ?? "Unknown Project",
                        t.AssignmentDate,
                        t.PlannedTask,
                        t.CompletedTask,
                        Location = $"{t.BuildingName} > {t.FloorName} > {t.AreaName}",
                        ActivityName = t.ActivityName,
                        ActivityUnit = t.ActivityUnit
                    };
                }).ToList();

                _logger.LogInfo("Successfully prepared task response for EmployeeId: {EmployeeId}", employeeId);

                return ApiResponse<object>.SuccessResponse(response, "Task fetched successfully", 200);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error while fetching tasks for EmployeeId: {EmployeeId}", employeeId);
                return ApiResponse<object>.ErrorResponse("An error occurred while fetching the tasks.", 500);
            }
        }

        #endregion

        #region =================================================================== Project Infrastructre Manage APIs ===================================================================

        public async Task<ServiceResponse> ManageProjectInfraAsync(List<InfraDto> infraDtos, Guid tenantId, Employee loggedInEmployee)
        {
            // 1. Guard Clause: Handle null or empty input gracefully.
            if (infraDtos == null || !infraDtos.Any())
            {
                return new ServiceResponse
                {
                    Response = ApiResponse<object>.ErrorResponse("Invalid details.", "No infrastructure details were provided.", 400)
                };
            }

            var responseData = new InfraVM();
            var messages = new List<string>();
            var projectIds = new HashSet<Guid>(); // Use HashSet for automatic duplicate handling.
            var cacheUpdateTasks = new List<Task>();

            // --- Pre-fetch parent entities to avoid N+1 query problem ---
            // 2. Gather all parent IDs needed for validation and context.
            var requiredBuildingIds = infraDtos
                .Where(i => i.Floor?.BuildingId != null)
                .Select(i => i.Floor!.BuildingId)
                .Distinct()
                .ToList();

            var requiredFloorIds = infraDtos
                .Where(i => i.WorkArea?.FloorId != null)
                .Select(i => i.WorkArea!.FloorId)
                .Distinct()
                .ToList();

            // 3. Fetch all required parent entities in single batch queries.
            var buildingsDict = await _context.Buildings
                .Where(b => requiredBuildingIds.Contains(b.Id))
                .ToDictionaryAsync(b => b.Id);

            var floorsDict = await _context.Floor
                .Include(f => f.Building) // Eagerly load Building for later use
                .Where(f => requiredFloorIds.Contains(f.Id))
                .ToDictionaryAsync(f => f.Id);
            // --- End Pre-fetching ---

            // 4. Process all entities and add them to the context's change tracker.
            foreach (var item in infraDtos)
            {
                if (item.Building != null)
                {
                    ProcessBuilding(item.Building, tenantId, responseData, messages, projectIds, cacheUpdateTasks, loggedInEmployee);
                }
                if (item.Floor != null)
                {
                    ProcessFloor(item.Floor, tenantId, responseData, messages, projectIds, cacheUpdateTasks, buildingsDict, loggedInEmployee);
                }
                if (item.WorkArea != null)
                {
                    ProcessWorkArea(item.WorkArea, tenantId, responseData, messages, projectIds, cacheUpdateTasks, floorsDict, loggedInEmployee);
                }
            }

            // 5. Save all changes to the database in a single transaction.
            var changedRecordCount = await _context.SaveChangesAsync();

            // If no changes were actually made, we can exit early.
            if (changedRecordCount == 0)
            {
                return new ServiceResponse
                {
                    Response = ApiResponse<object>.SuccessResponse(responseData, "No changes detected in the provided infrastructure details.", 200)
                };
            }

            // 6. Execute all cache updates concurrently after the DB save is successful.
            await Task.WhenAll(cacheUpdateTasks);

            // 7. Consolidate messages and create notification payload.
            string finalResponseMessage = messages.LastOrDefault() ?? "Infrastructure managed successfully.";
            string logMessage = $"{string.Join(", ", messages)} by {loggedInEmployee.FirstName} {loggedInEmployee.LastName}";
            var notification = new { LoggedInUserId = loggedInEmployee.Id, Keyword = "Infra", ProjectIds = projectIds.ToList(), Message = logMessage };

            // TODO: Dispatch the 'notification' object to your notification service.

            return new ServiceResponse
            {
                Notification = notification,
                Response = ApiResponse<object>.SuccessResponse(responseData, finalResponseMessage, 200)
            };
        }

        /// <summary>
        /// Creates or updates a batch of work items.
        /// This method is optimized to perform all database operations in a single, atomic transaction.
        /// </summary>
        public async Task<ApiResponse<List<WorkItemVM>>> CreateProjectTaskAsync(List<WorkItemDto> workItemDtos, Guid tenantId, Employee loggedInEmployee)
        {
            _logger.LogInfo("CreateProjectTask called with {Count} items by user {UserId}", workItemDtos?.Count ?? 0, loggedInEmployee.Id);

            using var scope = _serviceScopeFactory.CreateScope();
            var _firebase = scope.ServiceProvider.GetRequiredService<IFirebaseService>();

            var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();

            // --- Step 1: Input Validation ---
            if (workItemDtos == null || !workItemDtos.Any())
            {
                _logger.LogWarning("No work items provided in the request.");
                return ApiResponse<List<WorkItemVM>>.ErrorResponse("Invalid details.", "Work Item details list cannot be empty.", 400);
            }

            // --- Step 2: Fetch all required existing data in bulk ---
            var workAreaIds = workItemDtos.Select(d => d.WorkAreaID).Distinct().ToList();
            var workItemIdsToUpdate = workItemDtos.Where(d => d.Id.HasValue).Select(d => d.Id!.Value).ToList();

            // Fetch all relevant WorkAreas and their parent hierarchy in ONE query
            var workAreasFromDb = await _context.WorkAreas
                .Where(wa => wa.Floor != null && wa.Floor.Building != null && workAreaIds.Contains(wa.Id) && wa.TenantId == tenantId)
                .Include(wa => wa.Floor!.Building) // Eagerly load the entire path
                .ToDictionaryAsync(wa => wa.Id); // Dictionary for fast lookups

            // Fetch all existing WorkItems that need updating in ONE query
            var existingWorkItemsToUpdate = await _context.WorkItems
                .Where(wi => workItemIdsToUpdate.Contains(wi.Id) && wi.TenantId == tenantId)
                .ToDictionaryAsync(wi => wi.Id); // Dictionary for fast lookups

            // --- (Placeholder) Security Check ---
            // You MUST verify the user has permission to modify ALL WorkAreas in the batch.
            var projectIdsInBatch = workAreasFromDb.Values.Select(wa => wa.Floor!.Building!.ProjectId).Distinct();
            var hasPermission = await _permission.HasPermission(PermissionsMaster.ManageProjectInfra, loggedInEmployee.Id, projectIdsInBatch.FirstOrDefault());
            if (!hasPermission)
            {
                _logger.LogWarning("Access DENIED for user {UserId} trying to create/update tasks.", loggedInEmployee.Id);
                return ApiResponse<List<WorkItemVM>>.ErrorResponse("Access Denied.", "You do not have permission to modify tasks in one or more of the specified work areas.", 403);
            }

            var workItemsToCreate = new List<WorkItem>();
            var workItemsToModify = new List<WorkItem>();
            var workDeltaForCache = new Dictionary<Guid, (double Planned, double Completed)>(); // WorkAreaId -> (Delta)
            string message = "";

            // --- Step 3: Process all logic IN MEMORY, tracking changes ---
            foreach (var dto in workItemDtos)
            {
                if (!workAreasFromDb.TryGetValue(dto.WorkAreaID, out var workArea))
                {
                    _logger.LogWarning("Skipping item because WorkAreaId {WorkAreaId} was not found or is invalid.", dto.WorkAreaID);
                    continue; // Skip this item as its parent WorkArea is invalid
                }

                if (dto.Id.HasValue && existingWorkItemsToUpdate.TryGetValue(dto.Id.Value, out var existingWorkItem))
                {
                    // --- UPDATE Logic ---
                    var plannedDelta = dto.PlannedWork - existingWorkItem.PlannedWork;
                    var completedDelta = dto.CompletedWork - existingWorkItem.CompletedWork;

                    // Apply changes from DTO to the fetched entity to prevent data loss
                    _mapper.Map(dto, existingWorkItem);
                    workItemsToModify.Add(existingWorkItem);

                    // Track the change in work for cache update
                    workDeltaForCache[workArea.Id] = (
                        workDeltaForCache.GetValueOrDefault(workArea.Id).Planned + plannedDelta,
                        workDeltaForCache.GetValueOrDefault(workArea.Id).Completed + completedDelta
                    );
                    message = $"Task Updated in Building: {workArea.Floor?.Building?.Name}, on Floor: {workArea.Floor?.FloorName}, in Area: {workArea.AreaName} by {loggedInEmployee.FirstName} {loggedInEmployee.LastName}";
                }
                else
                {
                    // --- CREATE Logic ---
                    var newWorkItem = _mapper.Map<WorkItem>(dto);
                    newWorkItem.Id = Guid.NewGuid(); // Ensure new GUID is set
                    newWorkItem.TenantId = tenantId;
                    workItemsToCreate.Add(newWorkItem);

                    // Track the change in work for cache update
                    workDeltaForCache[workArea.Id] = (
                        workDeltaForCache.GetValueOrDefault(workArea.Id).Planned + newWorkItem.PlannedWork,
                        workDeltaForCache.GetValueOrDefault(workArea.Id).Completed + newWorkItem.CompletedWork
                    );
                    message = $"Task Added in Building: {workArea.Floor?.Building?.Name}, on Floor: {workArea.Floor?.FloorName}, in Area: {workArea.AreaName} by {loggedInEmployee.FirstName} {loggedInEmployee.LastName}";
                }
            }

            try
            {
                // --- Step 4: Save all database changes in a SINGLE TRANSACTION ---
                if (workItemsToCreate.Any()) _context.WorkItems.AddRange(workItemsToCreate);
                if (workItemsToModify.Any()) _context.WorkItems.UpdateRange(workItemsToModify); // EF Core handles individual updates correctly here

                if (workItemsToCreate.Any() || workItemsToModify.Any())
                {
                    await _context.SaveChangesAsync();
                    _logger.LogInfo("Successfully saved {CreatedCount} new and {UpdatedCount} updated work items.", workItemsToCreate.Count, workItemsToModify.Count);

                    // --- Step 5: Update Cache and SignalR AFTER successful DB save ---
                    var allAffectedItems = workItemsToCreate.Concat(workItemsToModify).ToList();

                    await UpdateCacheAndNotify(workDeltaForCache, allAffectedItems);
                }
            }
            catch (DbUpdateException ex)
            {
                _logger.LogError(ex, "A database error occurred while creating/updating tasks.");
                return ApiResponse<List<WorkItemVM>>.ErrorResponse("Database Error", "Failed to save changes.", 500);
            }

            // --- Step 6: Prepare and return the response ---
            var allProcessedItems = workItemsToCreate.Concat(workItemsToModify).ToList();
            var responseList = allProcessedItems.Select(wi => new WorkItemVM
            {
                WorkItemId = wi.Id,
                WorkItem = wi
            }).ToList();

            _ = Task.Run(async () =>
            {
                // --- Push Notification Section ---
                // This section attempts to send a test push notification to the user's device.
                // It's designed to fail gracefully and handle invalid Firebase Cloud Messaging (FCM) tokens.

                var name = $"{loggedInEmployee.FirstName} {loggedInEmployee.LastName}";

                List<Guid> workItemIds = new List<Guid>();
                bool IsExist = false;

                if (workItemsToCreate.Any())
                    workItemIds = workItemsToCreate.Select(wi => wi.Id).ToList();
                if (workItemsToModify.Any())
                {
                    workItemIds = workItemsToModify.Select(wi => wi.Id).ToList();
                    IsExist = true;
                }

                if (workItemIds.Any())
                    await _firebase.SendModifyTaskMeaasgeAsync(workItemIds, name, IsExist, tenantId);

            });

            return ApiResponse<List<WorkItemVM>>.SuccessResponse(responseList, message, 200);
        }
        public async Task<ServiceResponse> DeleteProjectTaskAsync(Guid id, Guid tenantId, Employee loggedInEmployee)
        {
            using var scope = _serviceScopeFactory.CreateScope();
            var _firebase = scope.ServiceProvider.GetRequiredService<IFirebaseService>();

            // 1. Fetch the task and its parent data in a single query.
            // This is still a major optimization, avoiding a separate query for the floor/building.
            WorkItem? task = await _context.WorkItems
                .AsNoTracking() // Use AsNoTracking because we will re-attach for deletion later.
                .Include(t => t.WorkArea)
                    .ThenInclude(wa => wa!.Floor)
                    .ThenInclude(f => f!.Building)
                .FirstOrDefaultAsync(t => t.Id == id && t.TenantId == tenantId);

            // 2. Guard Clause: Handle non-existent task.
            if (task == null)
            {
                _logger.LogWarning("Attempted to delete a non-existent task with ID {WorkItemId}", id);
                return new ServiceResponse
                {
                    Response = ApiResponse<object>.ErrorResponse("Task not found.", $"A task with ID {id} was not found.", 404)
                };
            }

            // 3. Guard Clause: Prevent deletion if work has started.
            if (task.CompletedWork > 0)
            {
                double percentage = Math.Round((task.CompletedWork / task.PlannedWork) * 100, 2);
                _logger.LogWarning("Task with ID {WorkItemId} is {CompletionPercentage}% complete and cannot be deleted.", task.Id, percentage);
                return new ServiceResponse
                {
                    Response = ApiResponse<object>.ErrorResponse($"Task is {percentage}% complete and cannot be deleted.", "Deletion failed because the task has progress.", 400)
                };
            }

            // 4. Guard Clause: Efficiently check if the task is assigned in a separate, optimized query.
            // AnyAsync() is highly efficient and translates to a `SELECT TOP 1` or `EXISTS` in SQL.
            bool isAssigned = await _context.TaskAllocations.AnyAsync(t => t.WorkItemId == id);
            if (isAssigned)
            {
                _logger.LogWarning("Task with ID {WorkItemId} is currently assigned and cannot be deleted.", task.Id);
                return new ServiceResponse
                {
                    Response = ApiResponse<object>.ErrorResponse("Task is currently assigned and cannot be deleted.", "Deletion failed because the task is assigned to an employee.", 400)
                };
            }

            // --- Success Path: All checks passed, proceed with deletion ---

            var building = task.WorkArea?.Floor?.Building;
            var notification = new
            {
                LoggedInUserId = loggedInEmployee.Id,
                Keyword = "WorkItem",
                WorkAreaIds = new[] { task.WorkAreaId },
                Message = $"Task Deleted in Building: {building?.Name ?? "N/A"}, on Floor: {task.WorkArea?.Floor?.FloorName ?? "N/A"}, in Area: {task.WorkArea?.AreaName ?? "N/A"} by {loggedInEmployee.FirstName} {loggedInEmployee.LastName}"
            };

            // 5. Perform the database deletion.
            // We must attach a new instance or the original one without AsNoTracking.
            // Since we used AsNoTracking, we create a 'stub' entity for deletion.
            // This is more efficient than re-querying.
            _context.WorkItems.Remove(new WorkItem { Id = task.Id });
            await _context.SaveChangesAsync();
            _logger.LogInfo("Task with ID {WorkItemId} has been successfully deleted.", task.Id);

            // 6. Perform cache operations concurrently.
            var cacheTasks = new List<Task>
            {
                _cache.DeleteWorkItemByIdAsync(task.Id)
            };

            if (building?.ProjectId != null)
            {
                cacheTasks.Add(_cache.DeleteProjectByIdAsync(building.ProjectId));
            }
            await Task.WhenAll(cacheTasks);
            _ = Task.Run(async () =>
            {
                // --- Push Notification Section ---
                // This section attempts to send a test push notification to the user's device.
                // It's designed to fail gracefully and handle invalid Firebase Cloud Messaging (FCM) tokens.

                var name = $"{loggedInEmployee.FirstName} {loggedInEmployee.LastName}";

                await _firebase.SendDeleteTaskMeaasgeAsync(task.Id, name, tenantId);

            });
            // 7. Return the final success response.
            return new ServiceResponse
            {
                Notification = notification,
                Response = ApiResponse<object>.SuccessResponse(new { id = task.Id }, "Task deleted successfully.", 200)
            };
        }

        #endregion

        #region =================================================================== Project-Level Permission APIs ===================================================================

        /// <summary>
        /// Manages project-level permissions for an employee, optimizing DB calls and operations.
        /// </summary>
        /// <param name="model">Project-level permission DTO.</param>
        /// <param name="tenantId">Tenant Guid.</param>
        /// <param name="loggedInEmployee">Currently logged in employee.</param>
        /// <returns>API response indicating the result.</returns>
        public async Task<ApiResponse<object>> ManageProjectLevelPermissionAsync(ProjctLevelPermissionDto model, Guid tenantId, Employee loggedInEmployee)
        {
            // Log: Method entry and received parameters
            _logger.LogInfo("ManageProjectLevelPermissionAsync started for EmployeeId: {EmployeeId}, ProjectId: {ProjectId}, TenantId: {TenantId}",
                model.EmployeeId, model.ProjectId, tenantId);

            using var scope = _serviceScopeFactory.CreateScope();
            var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();

            var hasTeamPermission = await _permission.HasPermission(PermissionsMaster.ManageTeam, loggedInEmployee.Id, model.ProjectId);
            if (!hasTeamPermission)
            {
                _logger.LogWarning("Access Denied. User {UserId} tried to Manage the project-level permission for Employee {EmployeeId} and Project {ProjectId}"
                    , loggedInEmployee.Id, model.EmployeeId, model.ProjectId);
                return ApiResponse<object>.ErrorResponse("Access Denied.", "You do not have permission to Manage the project-level permission", 403);
            }

            // Fetch all required entities in parallel where possible
            var featurePermissionIds = model.Permission.Select(p => p.Id).ToList();

            // Log: Starting DB queries
            _logger.LogDebug("Fetching employee, project, feature permissions, and existing mappings.");

            var employeeTask = Task.Run(async () =>
            {
                await using var context = await _dbContextFactory.CreateDbContextAsync();
                return await context.ProjectAllocations.Include(pa => pa.Employee)
                .AsNoTracking()
                .Where(pa => pa.EmployeeId == model.EmployeeId && pa.ProjectId == model.ProjectId && pa.TenantId == tenantId && pa.IsActive)
                .Select(pa => pa.Employee).FirstOrDefaultAsync();
            });

            var projectTask = Task.Run(async () =>
            {
                await using var context = await _dbContextFactory.CreateDbContextAsync();
                return await context.Projects.AsNoTracking().FirstOrDefaultAsync(p => p.Id == model.ProjectId && p.TenantId == tenantId);
            });

            var featurePermissionsTask = Task.Run(async () =>
            {
                var featurePermissionIds = model.Permission.Select(p => p.Id).ToList();
                await using var context = await _dbContextFactory.CreateDbContextAsync();
                return await context.FeaturePermissions.AsNoTracking().Where(p => featurePermissionIds.Contains(p.Id)).ToListAsync();
            });

            var oldProjectLevelMappingTask = Task.Run(async () =>
            {
                await using var context = await _dbContextFactory.CreateDbContextAsync();
                return await context.ProjectLevelPermissionMappings
                .AsNoTracking()
                .Where(p => p.EmployeeId == model.EmployeeId && p.ProjectId == model.ProjectId && p.TenantId == tenantId).ToListAsync();
            });

            await Task.WhenAll(employeeTask, projectTask, featurePermissionsTask, oldProjectLevelMappingTask);

            var employee = employeeTask.Result;
            var project = projectTask.Result;
            var featurePermissions = featurePermissionsTask.Result;
            var oldProjectLevelMapping = oldProjectLevelMappingTask.Result;

            // Validate all loaded entities
            if (employee == null)
            {
                _logger.LogWarning("Employee not found: {EmployeeId}", model.EmployeeId);
                return ApiResponse<object>.ErrorResponse("Employee not found", "Employee not found in database", 404);
            }
            if (project == null)
            {
                _logger.LogWarning("Project not found: {ProjectId}", model.ProjectId);
                return ApiResponse<object>.ErrorResponse("Project not found", "Project not found in database", 404);
            }
            if (!(featurePermissions?.Any() ?? false))
            {
                _logger.LogWarning("No feature permissions found for provided ids");
                return ApiResponse<object>.ErrorResponse("No permission found", "No permission found in database", 404);
            }
            _logger.LogDebug("All entities loaded successfully for permission processing.");

            // Permission diff logic: Add new, Remove old
            var oldProjectLevelPermissionIds = oldProjectLevelMapping.Select(p => p.PermissionId).ToList();

            var newProjectLevelPermissions = model.Permission
                .Where(p => p.IsEnabled && !oldProjectLevelPermissionIds.Contains(p.Id))
                .Select(p => new ProjectLevelPermissionMapping
                {
                    EmployeeId = model.EmployeeId,
                    ProjectId = model.ProjectId,
                    PermissionId = p.Id,
                    TenantId = tenantId
                }).ToList();

            var deleteProjectLevelPermissions = oldProjectLevelMapping
                .Where(pl => model.Permission.Any(p => !p.IsEnabled && p.Id == pl.PermissionId))
                .ToList();

            // Apply permission changes
            if (newProjectLevelPermissions.Any())
            {
                _context.ProjectLevelPermissionMappings.AddRange(newProjectLevelPermissions);
                _logger.LogInfo("Added {Count} new project-level permissions.", newProjectLevelPermissions.Count);
            }

            if (deleteProjectLevelPermissions.Any())
            {
                _context.ProjectLevelPermissionMappings.RemoveRange(deleteProjectLevelPermissions);
                _logger.LogInfo("Removed {Count} old project-level permissions.", deleteProjectLevelPermissions.Count);
            }

            await _context.SaveChangesAsync();
            _logger.LogInfo("Project-level permission changes persisted for EmployeeId: {EmployeeId}, ProjectId: {ProjectId}", model.EmployeeId, model.ProjectId);

            // Final permissions for response
            var permissions = await _context.ProjectLevelPermissionMappings
                .Include(p => p.Permission)
                .AsNoTracking()
                .Where(p => p.EmployeeId == model.EmployeeId && p.ProjectId == model.ProjectId && p.TenantId == tenantId)
                .Select(p => _mapper.Map<FeaturePermissionVM>(p.Permission))
                .ToListAsync();

            _logger.LogInfo("ManageProjectLevelPermissionAsync completed successfully.");

            var response = new
            {
                EmployeeId = _mapper.Map<BasicEmployeeVM>(employee),
                ProjectId = _mapper.Map<BasicProjectVM>(project),
                Permissions = permissions
            };

            return ApiResponse<object>.SuccessResponse(response, "Project-Level permission assigned successfully", 200);
        }

        /// <summary>
        /// Retrieves the project-level permissions assigned to a specific employee for a given project and tenant.
        /// </summary>
        /// <param name="employeeId">Unique identifier of the employee.</param>
        /// <param name="projectId">Unique identifier of the project.</param>
        /// <param name="tenantId">Unique identifier of the tenant.</param>
        /// <param name="loggedInEmployee">The authenticated employee making this request.</param>
        /// <returns>ApiResponse containing the permission mappings or error details.</returns>
        public async Task<ApiResponse<object>> GetAssignedProjectLevelPermissionAsync(Guid employeeId, Guid projectId, Guid tenantId, Employee loggedInEmployee)
        {
            // Log the attempt to fetch project-level permissions
            _logger.LogInfo(
                "Fetching project-level permissions for EmployeeId: {EmployeeId}, ProjectId: {ProjectId}, TenantId: {TenantId} by {LoggedInEmployeeId}",
                employeeId, projectId, tenantId, loggedInEmployee.Id);

            // Query the database for relevant project-level permission mappings
            var employeeTask = Task.Run(async () =>
            {
                await using var context = await _dbContextFactory.CreateDbContextAsync();
                return await context.Employees.FirstOrDefaultAsync(e => e.Id == employeeId);
            });
            var projectTask = Task.Run(async () =>
            {
                await using var context = await _dbContextFactory.CreateDbContextAsync();
                return await context.Projects.FirstOrDefaultAsync(p => p.Id == projectId && p.TenantId == tenantId);
            });
            var permissionIdsTask = Task.Run(async () =>
            {
                return await GetPermissionIdsByProject(projectId, employeeId, tenantId);
            });

            await Task.WhenAll(employeeTask, projectTask, permissionIdsTask);

            var employee = employeeTask.Result;
            var project = projectTask.Result;
            var permissionIds = permissionIdsTask.Result;

            var permissions = await _context.FeaturePermissions
                .Include(fp => fp.Feature)
                .Where(fp => permissionIds.Contains(fp.Id)).ToListAsync();

            if (employee == null)
            {
                _logger.LogWarning("Employee record missing for EmployeeId: {EmployeeId}", employeeId);
                return ApiResponse<object>.ErrorResponse("Employee not found", "Employee not found in database", 404);
            }
            if (project == null)
            {
                _logger.LogWarning("Project record missing for ProjectId: {ProjectId}", projectId);
                return ApiResponse<object>.ErrorResponse("Project not found", "Project not found in database", 404);
            }

            if (permissions == null || !permissions.Any())
            {
                _logger.LogWarning("No project-level permissions found for EmployeeId: {EmployeeId}, ProjectId: {ProjectId}, TenantId: {TenantId}",
                    employeeId, projectId, tenantId);
                return ApiResponse<object>.ErrorResponse("Project-Level Permissions not found", "Project-Level Permissions not found in database", 404);
            }

            // Map the employee, project, and permissions.
            var employeeVm = _mapper.Map<BasicEmployeeVM>(employee);
            var projectVm = _mapper.Map<BasicProjectVM>(project);
            var permissionVms = permissions
                .Select(p => _mapper.Map<FeaturePermissionVM>(p))
                .ToList();

            // Prepare the result object.
            var result = new
            {
                Employee = employeeVm,
                Project = projectVm,
                Permissions = permissionVms
            };

            _logger.LogInfo("Project-level permissions fetched successfully for EmployeeId: {EmployeeId}, ProjectId: {ProjectId}, TenantId: {TenantId}",
                employeeId, projectId, tenantId);

            return ApiResponse<object>.SuccessResponse(result, "Project-Level Permissions fetched successfully", 200);
        }

        /// <summary>
        /// Assigns features at the project module level for the given tenant and employee.
        /// </summary>
        /// <param name="tenantId">Tenant ID associated with assignment.</param>
        /// <param name="loggedInEmployee">Logged-in employee context.</param>
        /// <returns>API response containing feature details associated with specified modules.</returns>
        public async Task<ApiResponse<object>> AssignProjectLevelModulesAsync(Guid tenantId, Employee loggedInEmployee)
        {
            // Log entry at the start of the method.
            _logger.LogInfo("AssignProjectLevelModulesAsync called for TenantId: {TenantId}, EmployeeId: {EmployeeId}", tenantId, loggedInEmployee.Id);

            // Define target module IDs. These could alternatively be stored in a config file or DB.
            var projectLevelModuleIds = new HashSet<Guid>
            {
                Guid.Parse("53176ebf-c75d-42e5-839f-4508ffac3def"),
                Guid.Parse("9d4b5489-2079-40b9-bd77-6e1bf90bc19f"),
                Guid.Parse("52c9cf54-1eb2-44d2-81bb-524cf29c0a94"),
                Guid.Parse("a8cf4331-8f04-4961-8360-a3f7c3cc7462")
            };

            try
            {
                // Query features associated with specified modules. Also include module and permissions.
                _logger.LogDebug("Querying Features with module filters: {ModuleIds}", string.Join(", ", projectLevelModuleIds));

                var features = await _context.Features
                    .AsNoTracking() // Improves read-only query performance
                    .Include(f => f.FeaturePermissions)
                    .Include(f => f.Module)
                    .Where(f => projectLevelModuleIds.Contains(f.Id) && f.Module != null)
                    .Select(f => new FeatureVM
                    {
                        Id = f.Id,
                        Name = f.Name,
                        Description = f.Description,
                        FeaturePermissions = _mapper.Map<List<FeaturePermissionVM>>(f.FeaturePermissions),
                        ModuleId = f.ModuleId,
                        ModuleName = f.Module!.Name,
                        IsActive = f.IsActive,
                        ModuleKey = f.Module!.Key
                    })
                    .ToListAsync();

                _logger.LogInfo("Features successfully retrieved for TenantId: {TenantId}. FeatureCount: {FeatureCount}", tenantId, features.Count);

                // Return successful response.
                return ApiResponse<object>.SuccessResponse(features, "Feature Permission for project-level is fetched successfully", 200);
            }
            catch (Exception ex)
            {
                // Log the error for further diagnostics.
                _logger.LogError(ex, "Error in AssignProjectLevelModulesAsync for TenantId: {TenantId}, EmployeeId: {EmployeeId}", tenantId, loggedInEmployee.Id);

                // Return an appropriate error response to consumer.
                return ApiResponse<object>.ErrorResponse("Failed to assign project-level modules.", ex.Message);
            }
        }
        public async Task<ApiResponse<object>> GetEmployeeToWhomProjectLevelAssignedAsync(Guid projectId, Guid tenantId, Employee loggedInEmployee)
        {
            // Log method entry and parameters for traceability
            _logger.LogInfo("Fetching employees with project-level permissions. ProjectId: {ProjectId}, TenantId: {TenantId}, RequestedBy: {EmployeeId}",
                projectId, tenantId, loggedInEmployee.Id);

            try
            {
                // Optimized query: Selecting only employees with necessary joins
                // Instead of fetching entire mapping objects, directly project required employees
                var assignedEmployees = await _context.ProjectLevelPermissionMappings
                    .Include(pl => pl.Employee)
                        .ThenInclude(e => e!.JobRole)
                    .AsNoTracking()
                    .Where(pl => pl.ProjectId == projectId && pl.TenantId == tenantId)
                    .Select(pl => pl.Employee)                // only employees
                    .Distinct()                               // ensure unique employees
                    .ToListAsync();

                _logger.LogInfo("Retrieved {Count} employees with project-level permissions for ProjectId: {ProjectId}, TenantId: {TenantId}",
                    assignedEmployees.Count, projectId, tenantId);

                // Use AutoMapper to transform DB entities into VMs
                var response = _mapper.Map<List<BasicEmployeeVM>>(assignedEmployees);

                // Return a consistent API response with success message
                return ApiResponse<object>.SuccessResponse(response, "The list of employees with project-level permissions has been successfully retrieved.", 200);
            }
            catch (Exception ex)
            {
                // Log exception details for debugging
                _logger.LogError(ex, "Error occurred while fetching employees for ProjectId: {ProjectId}, TenantId: {TenantId}, RequestedBy: {EmployeeId}",
                    projectId, tenantId, loggedInEmployee.Id);

                // Return standard error response
                return ApiResponse<object>.ErrorResponse("An error occurred while retrieving employees with project-level permissions.", 500);
            }
        }
        public async Task<ApiResponse<object>> GetAllPermissionFroProjectAsync(Guid projectId, Employee loggedInEmployee, Guid tenantId)
        {
            var featurePermissionIds = await GetPermissionIdsByProject(projectId, loggedInEmployee.Id, tenantId);
            return ApiResponse<object>.SuccessResponse(featurePermissionIds, "Successfully featched the permission ids", 200);
        }
        #endregion

        #region =================================================================== Assign Service APIs ===================================================================

        /// <summary>
        /// Retrieves the list of services assigned to a specific project based on the logged-in employee's organization and permissions.
        /// </summary>
        /// <param name="projectId">The unique identifier of the project.</param>
        /// <param name="tenantId">The tenant identifier for multi-tenant data isolation.</param>
        /// <param name="loggedInEmployee">The employee making the request, whose permissions are checked.</param>
        /// <returns>An ApiResponse containing the list of assigned services or an error response.</returns>
        public async Task<ApiResponse<object>> GetAssignedServiceToProjectAsync(Guid projectId, Guid tenantId, Employee loggedInEmployee)
        {
            try
            {
                using var scope = _serviceScopeFactory.CreateScope();
                var permissionService = scope.ServiceProvider.GetRequiredService<PermissionServices>();

                // Fetch the project to ensure it exists in the given tenant scope
                var project = await _context.Projects
                    .AsNoTracking() // No changes are made, so use NoTracking for performance
                    .FirstOrDefaultAsync(p => p.Id == projectId && p.TenantId == tenantId);

                if (project == null)
                {
                    _logger.LogWarning("Project not found. ProjectId: {ProjectId}, TenantId: {TenantId}", projectId, tenantId);
                    return ApiResponse<object>.ErrorResponse("Project not found", "Project not found in database", 404);
                }

                // Verify logged-in employee has permission on the project
                var hasPermission = await permissionService.HasProjectPermission(loggedInEmployee, projectId);
                if (!hasPermission)
                {
                    _logger.LogWarning("Access DENIED for user {UserId} attempting to access project {ProjectId}.", loggedInEmployee.Id, projectId);
                    return ApiResponse<object>.ErrorResponse("Access Denied.", "You do not have permission to access this project.", 403);
                }

                List<ServiceMaster> assignedServices;

                // Check if the logged-in employee's organization matches both Promoter and PMC of the project
                if (project.PromoterId == loggedInEmployee.OrganizationId && project.PMCId == loggedInEmployee.OrganizationId)
                {
                    // Get all active services assigned directly to the project within the tenant
                    assignedServices = await _context.ProjectServiceMappings
                        .AsNoTracking()
                        .Include(ps => ps.Service)
                        .Where(ps => ps.ProjectId == projectId && ps.IsActive && ps.TenantId == tenantId && ps.Service != null)
                        .Select(ps => ps.Service!)
                        .Distinct()
                        .ToListAsync();

                    _logger.LogInfo("User {UserId} requested all services for project {ProjectId} as Promoter and PMC.", loggedInEmployee.Id, projectId);
                }
                else
                {
                    // Get the active project services mapped to the employee's organization for this project
                    assignedServices = await _context.ProjectOrgMappings
                        .AsNoTracking()
                        .Include(po => po.ProjectService)
                            .ThenInclude(ps => ps!.Service)
                        .Where(po =>
                            po.OrganizationId == loggedInEmployee.OrganizationId &&
                            po.ProjectService != null &&
                            po.ProjectService.IsActive &&
                            po.ProjectService.ProjectId == projectId &&
                            po.ProjectService.Service != null)
                        .Select(po => po.ProjectService!.Service!)
                        .Distinct()
                        .ToListAsync();

                    _logger.LogInfo("User {UserId} requested services for project {ProjectId} via organization mapping.", loggedInEmployee.Id, projectId);
                }

                // Map entities to view models
                var serviceViewModels = _mapper.Map<List<ServiceMasterVM>>(assignedServices);

                return ApiResponse<object>.SuccessResponse(serviceViewModels, "Successfully fetched the services for this project", 200);
            }
            catch (DbUpdateException dbEx)
            {
                _logger.LogError(dbEx, "Database exception occurred while fetching assigned services to project {ProjectId} for tenant {TenantId}.", projectId, tenantId);
                return ApiResponse<object>.ErrorResponse("Internal error", "A database exception occurred", 500);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Unexpected exception occurred while fetching assigned services to project {ProjectId} for tenant {TenantId}.", projectId, tenantId);
                return ApiResponse<object>.ErrorResponse("Internal error", "An unexpected internal exception occurred", 500);
            }
        }

        /// <summary>
        /// Assigns one or multiple services to a project with specified planned and actual dates.
        /// Checks for project existence and employee permissions before assignment.
        /// </summary>
        /// <param name="model">Data transfer object containing project ID, list of service IDs, and planned dates.</param>
        /// <param name="tenantId">Tenant identifier for proper multi-tenant separation.</param>
        /// <param name="loggedInEmployee">The employee requesting the service assignment, used for permission checks.</param>
        /// <returns>ApiResponse with assigned services info or error details.</returns>
        public async Task<ApiResponse<object>> AssignServiceToProjectAsync(AssignServiceDto model, Guid tenantId, Employee loggedInEmployee)
        {
            // Begin a transaction to ensure atomicity of assignments
            await using var transaction = await _context.Database.BeginTransactionAsync();

            try
            {
                using var scope = _serviceScopeFactory.CreateScope();
                var permissionService = scope.ServiceProvider.GetRequiredService<PermissionServices>();

                // Validate project exists within the tenant
                var project = await _context.Projects
                    .AsNoTracking()
                    .FirstOrDefaultAsync(p => p.Id == model.ProjectId && p.TenantId == tenantId);

                if (project == null)
                {
                    _logger.LogWarning("Project not found. ProjectId: {ProjectId}, TenantId: {TenantId}", model.ProjectId, tenantId);
                    return ApiResponse<object>.ErrorResponse("Project not found", "Project not found in database", 404);
                }

                // Validate permission for logged-in employee to assign services to project
                var hasPermission = await permissionService.HasProjectPermission(loggedInEmployee, model.ProjectId);
                if (!hasPermission)
                {
                    _logger.LogWarning("Access DENIED for user {UserId} attempting to assign services to project {ProjectId}.", loggedInEmployee.Id, model.ProjectId);
                    return ApiResponse<object>.ErrorResponse("Access Denied", "You do not have permission to modify this project.", 403);
                }

                // Fetch existing active project service mappings for the requested service IDs, within the same tenant
                var existingProjectServices = await _context.ProjectServiceMappings
                    .Where(sp => model.ServiceIds.Contains(sp.ServiceId) && sp.ProjectId == model.ProjectId && sp.IsActive)
                    .ToListAsync();

                // Fetch service details for the provided service IDs within the tenant scope
                var services = await _context.ServiceMasters
                    .Where(s => model.ServiceIds.Contains(s.Id) && s.TenantId == tenantId)
                    .ToListAsync();

                // Current UTC timestamp for actual start date
                var currentUtc = DateTime.UtcNow;

                // Add new project service mappings if not already present
                foreach (var serviceId in model.ServiceIds)
                {
                    if (!existingProjectServices.Any(ps => ps.ServiceId == serviceId))
                    {
                        var newMapping = new ProjectServiceMapping
                        {
                            ProjectId = project.Id,
                            ServiceId = serviceId,
                            TenantId = tenantId,
                            PlannedStartDate = model.PlannedStartDate,
                            PlannedEndDate = model.PlannedEndDate,
                            ActualStartDate = currentUtc,
                            IsActive = true
                        };
                        _context.ProjectServiceMappings.Add(newMapping);
                        _logger.LogInfo("Assigned service {ServiceId} to project {ProjectId} by user {UserId}.", serviceId, model.ProjectId, loggedInEmployee.Id);
                    }
                    else
                    {
                        _logger.LogInfo("Service {ServiceId} is already assigned and active for project {ProjectId}.", serviceId, model.ProjectId);
                    }
                }

                await _context.SaveChangesAsync();
                await transaction.CommitAsync();

                // Prepare response combining project and service data mapped to view models
                var response = services.Select(s => new ProjectServiceVM
                {
                    Project = _mapper.Map<BasicProjectVM>(project),
                    Service = _mapper.Map<ServiceMasterVM>(s),
                    PlannedStartDate = model.PlannedStartDate,
                    PlannedEndDate = model.PlannedEndDate,
                    ActualStartDate = currentUtc
                }).ToList();

                return ApiResponse<object>.SuccessResponse(response, "Services have been assigned to the project successfully", 200);
            }
            catch (DbUpdateException dbEx)
            {
                await transaction.RollbackAsync();
                _logger.LogError(dbEx, "Database exception while assigning services to project {ProjectId} for tenant {TenantId} by user {UserId}.", model.ProjectId, tenantId, loggedInEmployee.Id);
                return ApiResponse<object>.ErrorResponse("Internal error", "A database exception has occurred", 500);
            }
            catch (Exception ex)
            {
                await transaction.RollbackAsync();
                _logger.LogError(ex, "Unexpected exception while assigning services to project {ProjectId} for tenant {TenantId} by user {UserId}.", model.ProjectId, tenantId, loggedInEmployee.Id);
                return ApiResponse<object>.ErrorResponse("Internal error", "An unexpected internal exception has occurred", 500);
            }
        }

        /// <summary>
        /// Deassigns specified services from a project by marking them inactive and setting actual end date.
        /// Validates project existence and employee permission before making updates.
        /// </summary>
        /// <param name="model">Contains ProjectId and list of ServiceIds to deassign.</param>
        /// <param name="tenantId">Tenant context for multi-tenant data isolation.</param>
        /// <param name="loggedInEmployee">Employee executing the operation, used for permission checks.</param>
        /// <returns>ApiResponse indicating success or failure.</returns>
        public async Task<ApiResponse<object>> DeassignServiceToProjectAsync(DeassignServiceDto model, Guid tenantId, Employee loggedInEmployee)
        {
            await using var transaction = await _context.Database.BeginTransactionAsync();

            try
            {
                using var scope = _serviceScopeFactory.CreateScope();
                var permissionService = scope.ServiceProvider.GetRequiredService<PermissionServices>();

                // Validate that project exists for given tenant
                var project = await _context.Projects
                    .AsNoTracking()
                    .FirstOrDefaultAsync(p => p.Id == model.ProjectId && p.TenantId == tenantId);

                if (project == null)
                {
                    _logger.LogWarning("Project not found. ProjectId: {ProjectId}, TenantId: {TenantId}", model.ProjectId, tenantId);
                    return ApiResponse<object>.ErrorResponse("Project not found", "Project not found in database", 404);
                }

                // Verify permission to update project
                var hasPermission = await permissionService.HasProjectPermission(loggedInEmployee, model.ProjectId);
                if (!hasPermission)
                {
                    _logger.LogWarning("Access DENIED for user {UserId} trying to deassign services from project {ProjectId}.", loggedInEmployee.Id, model.ProjectId);
                    return ApiResponse<object>.ErrorResponse("Access Denied", "You do not have permission to modify this project.", 403);
                }

                // Fetch active project service mappings matching provided service IDs
                var projectServices = await _context.ProjectServiceMappings
                    .Where(ps => model.ServiceIds.Contains(ps.ServiceId) && ps.ProjectId == model.ProjectId && ps.IsActive)
                    .ToListAsync();

                if (!projectServices.Any())
                {
                    _logger.LogWarning("No matching active project service mappings found for deassignment. ProjectId: {ProjectId}, ServiceIds: {ServiceIds}",
                        model.ProjectId, string.Join(",", model.ServiceIds));
                    return ApiResponse<object>.ErrorResponse("Project Service mapping not found", "No active service mappings found in database", 404);
                }

                var currentUtc = DateTime.UtcNow;

                // Mark mappings as inactive and set actual end date to now
                foreach (var ps in projectServices)
                {
                    ps.IsActive = false;
                    ps.ActualEndDate = currentUtc;
                }

                _context.ProjectServiceMappings.UpdateRange(projectServices);
                await _context.SaveChangesAsync();
                await transaction.CommitAsync();

                _logger.LogInfo("User {UserId} deassigned {Count} services from project {ProjectId}.", loggedInEmployee.Id, projectServices.Count, model.ProjectId);

                return ApiResponse<object>.SuccessResponse(new { }, "Services have been deassigned from the project successfully", 200);
            }
            catch (DbUpdateException dbEx)
            {
                await transaction.RollbackAsync();
                _logger.LogError(dbEx, "Database exception occurred while deassigning services from project {ProjectId} by user {UserId}.", model.ProjectId, loggedInEmployee.Id);
                return ApiResponse<object>.ErrorResponse("Internal error", "A database exception has occurred", 500);
            }
            catch (Exception ex)
            {
                await transaction.RollbackAsync();
                _logger.LogError(ex, "Unexpected exception occurred while deassigning services from project {ProjectId} by user {UserId}.", model.ProjectId, loggedInEmployee.Id);
                return ApiResponse<object>.ErrorResponse("Internal error", "An unexpected internal exception has occurred", 500);
            }
        }
        #endregion

        #region =================================================================== Assign Organization APIs ===================================================================

        public async Task<ApiResponse<object>> GetAssignedOrganizationsToProjectAsync(Guid projectId, Guid tenantId, Employee loggedInEmployee)
        {
            _logger.LogDebug("Started fetching assigned organizations for ProjectId: {ProjectId} and TenantId: {TenantId} by user {UserId}",
                projectId, tenantId, loggedInEmployee.Id);

            try
            {
                // Create a scoped PermissionServices instance for permission checks
                using var scope = _serviceScopeFactory.CreateScope();
                var permissionService = scope.ServiceProvider.GetRequiredService<PermissionServices>();

                // Retrieve the project by projectId and tenantId
                var project = await _context.Projects
                    .AsNoTracking()
                    .FirstOrDefaultAsync(p => p.Id == projectId && p.TenantId == tenantId);

                if (project == null)
                {
                    _logger.LogWarning("Project not found. ProjectId: {ProjectId}, TenantId: {TenantId}", projectId, tenantId);
                    return ApiResponse<object>.ErrorResponse("Project not found", "Project not found in database", 404);
                }

                // Check if the logged in employee has permission to access the project
                var hasPermission = await permissionService.HasProjectPermission(loggedInEmployee, projectId);
                if (!hasPermission)
                {
                    _logger.LogWarning("Access denied for user {UserId} on project {ProjectId}", loggedInEmployee.Id, projectId);
                    return ApiResponse<object>.ErrorResponse("Access Denied", "You do not have permission to access this project.", 403);
                }

                // Fetch all project-organization mappings with related service and organization data
                var projectOrgMappings = await _context.ProjectOrgMappings
                    .AsNoTracking()
                    .Include(po => po.ProjectService)
                        .ThenInclude(ps => ps!.Service)
                    .Include(po => po.Organization)
                    .Where(po => po.ProjectService != null
                              && po.ProjectService.ProjectId == projectId
                              && po.TenantId == tenantId)
                    .Distinct()
                    .ToListAsync();

                // Filter and map the data to the desired view model
                var response = projectOrgMappings
                    .Where(po => po.Organization != null)
                    .Select(po => new ProjectOrganizationVM
                    {
                        Id = po.Organization!.Id,
                        Name = po.Organization.Name,
                        Email = po.Organization.Email,
                        ContactPerson = po.Organization.ContactPerson,
                        SPRID = po.Organization.SPRID,
                        logoImage = po.Organization.logoImage,
                        AssignedBy = _mapper.Map<BasicEmployeeVM>(po.AssignedBy),
                        Service = _mapper.Map<ServiceMasterVM>(po.ProjectService!.Service),
                        AssignedDate = po.AssignedDate,
                        CompletionDate = po.CompletionDate
                    })
                    .ToList();

                _logger.LogInfo("Fetched {Count} assigned organizations for ProjectId: {ProjectId}", response.Count, projectId);

                return ApiResponse<object>.SuccessResponse(response, "Successfully fetched the list of organizations assigned to the project", 200);
            }
            catch (DbUpdateException dbEx)
            {
                _logger.LogError(dbEx, "Database exception while fetching assigned organizations for ProjectId: {ProjectId}", projectId);
                return ApiResponse<object>.ErrorResponse("Internal error", "A database exception occurred", 500);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Unhandled exception while fetching assigned organizations for ProjectId: {ProjectId}", projectId);
                return ApiResponse<object>.ErrorResponse("Internal error", "An internal exception occurred", 500);
            }
        }

        #endregion

        #region =================================================================== Helper Functions ===================================================================

        public async Task<List<Project>> GetAllProjectByTanentID(Guid tanentId)
        {
            List<Project> alloc = await _context.Projects.Where(c => c.TenantId == tanentId).ToListAsync();
            return alloc;
        }
        public async Task<List<ProjectAllocation>> GetProjectByEmployeeID(Guid employeeId)
        {
            List<ProjectAllocation> alloc = await _context.ProjectAllocations.Where(c => c.EmployeeId == employeeId && c.IsActive == true).Include(c => c.Project).ToListAsync();
            return alloc;
        }
        public async Task<List<ProjectAllocation>> GetTeamByProject(Guid TenantId, Guid ProjectId, Guid? OrganizationId, bool IncludeInactive)
        {
            var projectAllocationQuery = _context.ProjectAllocations
                    .Include(pa => pa.Employee)
                        .ThenInclude(e => e!.Organization)
                    .Where(pa => pa.TenantId == TenantId && pa.ProjectId == ProjectId);
            if (!IncludeInactive)
            {
                projectAllocationQuery = projectAllocationQuery.Where(pa => pa.IsActive);
            }
            if (OrganizationId.HasValue)
            {
                projectAllocationQuery = projectAllocationQuery.Where(pa => pa.Employee != null && pa.Employee.OrganizationId == OrganizationId);
            }
            var projectAllocation = await projectAllocationQuery.ToListAsync();
            return projectAllocation;
        }
        public async Task<List<Guid>> GetMyProjects(Guid tenantId, Employee LoggedInEmployee)
        {
            using var scope = _serviceScopeFactory.CreateScope();
            var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();

            var projectIds = await _cache.GetProjects(LoggedInEmployee.Id, tenantId);

            if (projectIds == null)
            {
                var hasPermission = await _permission.HasPermission(PermissionsMaster.ManageProject, LoggedInEmployee.Id);
                if (hasPermission)
                {
                    var projects = await _context.Projects.Where(c => c.TenantId == tenantId).ToListAsync();
                    projectIds = projects.Select(p => p.Id).ToList();
                }
                else
                {
                    var allocation = await GetProjectByEmployeeID(LoggedInEmployee.Id);
                    if (!allocation.Any())
                    {
                        return new List<Guid>();
                    }
                    projectIds = allocation.Select(c => c.ProjectId).Distinct().ToList();
                }
                await _cache.AddProjects(LoggedInEmployee.Id, projectIds, tenantId);
            }
            return projectIds;
        }
        public async Task<List<Guid>> GetMyProjectIdsAsync(Guid tenantId, Employee loggedInEmployee)
        {
            using var scope = _serviceScopeFactory.CreateScope();
            var _permission = scope.ServiceProvider.GetRequiredService<PermissionServices>();

            // 1. Attempt to retrieve the list of project IDs from the cache first.
            // This is the "happy path" and should be as fast as possible.
            List<Guid>? projectIds = await _cache.GetProjects(loggedInEmployee.Id, tenantId);

            if (projectIds != null)
            {
                // Cache Hit: Return the cached list immediately.
                return projectIds;
            }

            // 2. Cache Miss: The list was not in the cache, so we must fetch it from the database.
            List<Guid> newProjectIds;

            // Check for the specific permission.
            var hasPermission = await _permission.HasPermission(PermissionsMaster.ManageProject, loggedInEmployee.Id);

            if (hasPermission)
            {
                // 3a. OPTIMIZATION: User has permission to see all projects.
                // Fetch *only* the Ids directly from the database. This is far more efficient
                // than fetching full Project objects and then selecting the Ids in memory.
                newProjectIds = await _context.Projects
                    .Where(p => p.TenantId == tenantId)
                    .Select(p => p.Id) // This translates to `SELECT Id FROM Projects...` in SQL.
                    .ToListAsync();
            }
            else
            {
                // 3b. OPTIMIZATION: User can only see projects they are allocated to.
                // We go directly to the source (ProjectAllocations) and ask the database
                // for a distinct list of ProjectIds. This is much better than calling a
                // helper function that might return full allocation objects.
                newProjectIds = await _context.ProjectAllocations
                    .Where(a => a.EmployeeId == loggedInEmployee.Id && a.ProjectId != Guid.Empty)
                    .Select(a => a.ProjectId)
                    .Distinct() // Pushes the DISTINCT operation to the database.
                    .ToListAsync();
            }

            // 4. Populate the cache with the newly fetched list (even if it's empty).
            // This prevents repeated database queries for employees with no projects.
            await _cache.AddProjects(loggedInEmployee.Id, newProjectIds, tenantId);

            return newProjectIds;
        }

        /// <summary>
        /// Retrieves a list of ProjectInfoVMs by their IDs, using an efficient partial cache-hit strategy.
        /// It fetches what it can from the cache (as ProjectMongoDB), gets the rest from the 
        /// database (as Project), updates the cache, and returns a unified list of ViewModels.
        /// </summary>
        /// <param name="projectIds">The list of project IDs to retrieve.</param>
        /// <returns>A list of ProjectInfoVMs.</returns>
        private async Task<List<ProjectInfoVM>> GetProjectInfosByIdsAsync(List<Guid> projectIds)
        {
            // --- Step 1: Fetch from Cache ---
            // The cache returns a list of MongoDB documents for the projects it found.
            var cachedMongoDocs = await _cache.GetProjectDetailsList(projectIds) ?? new List<ProjectMongoDB>();
            var finalViewModels = _mapper.Map<List<ProjectInfoVM>>(cachedMongoDocs);

            _logger.LogDebug("Cache hit for {CacheCount} of {TotalCount} projects.", finalViewModels.Count, projectIds.Count);

            // --- Step 2: Identify Missing Projects ---
            // If we found everything in the cache, we can return early.
            if (finalViewModels.Count == projectIds.Count)
            {
                return finalViewModels;
            }

            var cachedIds = cachedMongoDocs.Select(p => p.Id).ToHashSet(); // Assuming ProjectMongoDB has an Id
            var missingIds = projectIds.Where(id => !cachedIds.Contains(id.ToString())).ToList();

            // --- Step 3: Fetch Missing from Database ---
            if (missingIds.Any())
            {
                _logger.LogDebug("Cache miss for {MissingCount} projects. Querying database.", missingIds.Count);

                var projectsFromDb = await _context.Projects
                    .Where(p => missingIds.Contains(p.Id))
                    .AsNoTracking() // Use AsNoTracking for read-only query performance
                    .ToListAsync();

                if (projectsFromDb.Any())
                {
                    // Map the newly fetched projects (from SQL) to their ViewModel
                    var vmsFromDb = _mapper.Map<List<ProjectInfoVM>>(projectsFromDb);
                    finalViewModels.AddRange(vmsFromDb);

                    // --- Step 4: Update Cache with Missing Items in a new scope ---
                    _logger.LogDebug("Updating cache with {DbCount} newly fetched projects.", projectsFromDb.Count);
                    await _cache.AddProjectDetailsList(projectsFromDb);
                }
            }

            return finalViewModels;
        }
        private async Task<ProjectDetailsVM> GetProjectViewModel(Guid? id, Project project)
        {
            ProjectDetailsVM vm = new ProjectDetailsVM();

            // List<Building> buildings = _unitOfWork.Building.GetAll(c => c.ProjectId == id).ToList();
            List<Building> buildings = await _context.Buildings.Where(c => c.ProjectId == id).ToListAsync();
            List<Guid> idList = buildings.Select(o => o.Id).ToList();
            // List<Floor> floors = _unitOfWork.Floor.GetAll(c => idList.Contains(c.Id)).ToList();
            List<Floor> floors = await _context.Floor.Where(c => idList.Contains(c.BuildingId)).ToListAsync();
            idList = floors.Select(o => o.Id).ToList();
            //List<WorkArea> workAreas = _unitOfWork.WorkArea.GetAll(c => idList.Contains(c.Id), includeProperties: "WorkItems,WorkItems.ActivityMaster").ToList();

            List<WorkArea> workAreas = await _context.WorkAreas.Where(c => idList.Contains(c.FloorId)).ToListAsync();

            idList = workAreas.Select(o => o.Id).ToList();
            List<WorkItem> workItems = await _context.WorkItems.Include(c => c.WorkCategoryMaster).Where(c => idList.Contains(c.WorkAreaId)).Include(c => c.ActivityMaster).ToListAsync();
            //  List <WorkItem> workItems = _unitOfWork.WorkItem.GetAll(c => idList.Contains(c.WorkAreaId), includeProperties: "ActivityMaster").ToList();
            idList = workItems.Select(t => t.Id).ToList();
            List<TaskAllocation> tasks = await _context.TaskAllocations.Where(t => idList.Contains(t.WorkItemId) && t.AssignmentDate.Date == DateTime.UtcNow.Date).ToListAsync();
            vm.project = project;
            vm.buildings = buildings;
            vm.floors = floors;
            vm.workAreas = workAreas;
            vm.workItems = workItems;
            vm.Tasks = tasks;
            return vm;
        }

        /// <summary>
        /// Fetches project details from the database for a given list of project IDs and assembles them into MongoDB models.
        /// This method encapsulates the optimized, parallel database queries.
        /// </summary>
        /// <param name="projectIdsToFetch">The list of project IDs to fetch.</param>
        /// <param name="tenantId">The current tenant ID for filtering.</param>
        /// <returns>A list of fully populated ProjectMongoDB objects.</returns>
        private async Task<List<ProjectListVM>> FetchAndBuildProjectDetails(List<Guid> projectIdsToFetch, Guid tenantId)
        {
            // Task to get base project details for the MISSING projects
            var projectsTask = Task.Run(async () =>
            {
                using var context = _dbContextFactory.CreateDbContext();
                return await context.Projects.AsNoTracking()
                    .Where(p => projectIdsToFetch.Contains(p.Id) && p.TenantId == tenantId)
                    .ToListAsync();
            });

            // Task to get team sizes for the MISSING projects
            var teamSizesTask = Task.Run(async () =>
            {
                using var context = _dbContextFactory.CreateDbContext();
                return await context.ProjectAllocations.AsNoTracking()
                    .Where(pa => pa.TenantId == tenantId && projectIdsToFetch.Contains(pa.ProjectId) && pa.IsActive)
                    .GroupBy(pa => pa.ProjectId)
                    .Select(g => new { ProjectId = g.Key, Count = g.Count() })
                    .ToDictionaryAsync(x => x.ProjectId, x => x.Count);
            });

            // Task to get work summaries for the MISSING projects
            var workSummariesTask = Task.Run(async () =>
            {
                using var context = _dbContextFactory.CreateDbContext();
                return await context.WorkItems.AsNoTracking()
                    .Where(wi => wi.TenantId == tenantId &&
                                 wi.WorkArea != null &&
                                 wi.WorkArea.Floor != null &&
                                 wi.WorkArea.Floor.Building != null &&
                                 projectIdsToFetch.Contains(wi.WorkArea.Floor.Building.ProjectId))
                    .GroupBy(wi => wi.WorkArea!.Floor!.Building!.ProjectId)
                    .Select(g => new { ProjectId = g.Key, PlannedWork = g.Sum(i => i.PlannedWork), CompletedWork = g.Sum(i => i.CompletedWork) })
                    .ToDictionaryAsync(x => x.ProjectId);
            });

            // Await all parallel tasks to complete
            await Task.WhenAll(projectsTask, teamSizesTask, workSummariesTask);

            var projects = await projectsTask;
            var teamSizes = await teamSizesTask;
            var workSummaries = await workSummariesTask;

            // Proactively update the cache with the items we just fetched.
            _logger.LogInfo("Updating cache with {NewItemCount} newly fetched projects.", projects.Count);
            await _cache.AddProjectDetailsList(projects);

            // This section would build the full ProjectMongoDB objects, similar to your AddProjectDetailsList method.
            // For brevity, assuming you have a mapper or a builder for this. Here's a simplified representation:
            var mongoDetailsList = new List<ProjectListVM>();
            foreach (var project in projects)
            {
                // This is a placeholder for the full build logic from your other methods.
                // In a real scenario, you would fetch all hierarchy levels (buildings, floors, etc.)
                // for the `projectIdsToFetch` and build the complete MongoDB object.
                var mongoDetail = _mapper.Map<ProjectListVM>(project);
                mongoDetail.Id = project.Id;
                mongoDetail.TeamSize = teamSizes.GetValueOrDefault(project.Id, 0);
                if (workSummaries.TryGetValue(project.Id, out var summary))
                {
                    mongoDetail.PlannedWork = summary.PlannedWork;
                    mongoDetail.CompletedWork = summary.CompletedWork;
                }
                mongoDetailsList.Add(mongoDetail);
            }

            return mongoDetailsList;
        }

        /// <summary>
        /// Private helper to encapsulate the cache-first data retrieval logic.
        /// </summary>
        /// <returns>A ProjectDetailVM if found, otherwise null.</returns>
        private async Task<Project?> GetProjectDataAsync(Guid projectId, Guid tenantId)
        {
            // --- Cache First ---
            _logger.LogDebug("Attempting to fetch project {ProjectId} from cache.", projectId);
            var cachedProject = await _cache.GetProjectDetails(projectId);
            if (cachedProject != null)
            {
                _logger.LogInfo("Cache HIT for project {ProjectId}.", projectId);
                // Map from the cache model (e.g., ProjectMongoDB) to the response ViewModel.
                return _mapper.Map<Project>(cachedProject);
            }

            // --- Database Second (on Cache Miss) ---
            _logger.LogInfo("Cache MISS for project {ProjectId}. Fetching from database.", projectId);
            var dbProject = await _context.Projects
                .AsNoTracking() // Use AsNoTracking for read-only queries.
                .Where(p => p.Id == projectId && p.TenantId == tenantId)
                .SingleOrDefaultAsync();

            if (dbProject == null)
            {
                return null; // The project doesn't exist.
            }

            // --- Proactively Update Cache ---
            // The next request for this project will now be a cache hit.
            try
            {
                // Map the DB entity to the cache model (e.g., ProjectMongoDB) before caching.
                await _cache.AddProjectDetails(dbProject);
                _logger.LogInfo("Updated cache with project {ProjectId}.", projectId);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Failed to update cache for project {ProjectId} : ", projectId);
            }

            // Map from the database entity to the response ViewModel.
            return dbProject;
        }
        private async Task UpdateCacheInBackground(Project project)
        {
            try
            {
                // This logic can be more complex, but the idea is to update or add.
                var demo = await _cache.UpdateProjectDetailsOnly(project);
                if (!demo)
                {
                    await _cache.AddProjectDetails(project);
                }
                _logger.LogInfo("Background cache update succeeded for project {ProjectId}.", project.Id);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Background cache update failed for project {ProjectId} ", project.Id);
            }
        }
        private async Task UpdateCacheAndNotify(Dictionary<Guid, (double Planned, double Completed)> workDelta, List<WorkItem> affectedItems)
        {
            try
            {
                // Update planned/completed work totals
                var cacheUpdateTasks = workDelta.Select(kvp =>
                    _cache.UpdatePlannedAndCompleteWorksInBuilding(kvp.Key, kvp.Value.Planned, kvp.Value.Completed));
                await Task.WhenAll(cacheUpdateTasks);
                _logger.LogInfo("Background cache work totals update completed for {AreaCount} areas.", workDelta.Count);

                // Update the details of the individual work items in the cache
                await _cache.ManageWorkItemDetails(affectedItems);
                _logger.LogInfo("Background cache work item details update completed for {ItemCount} items.", affectedItems.Count);

                // Add SignalR notification logic here if needed
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "An error occurred during background cache update/notification.");
            }
        }
        private void ProcessBuilding(BuildingDto dto, Guid tenantId, InfraVM responseData, List<string> messages, ISet<Guid> projectIds, List<Task> cacheTasks, Employee loggedInEmployee)
        {
            using var scope = _serviceScopeFactory.CreateScope();
            var _firebase = scope.ServiceProvider.GetRequiredService<IFirebaseService>();

            Building building = _mapper.Map<Building>(dto);
            building.TenantId = tenantId;

            bool isNew = dto.Id == null;
            if (isNew)
            {
                _context.Buildings.Add(building);
                messages.Add("Building Added");
                cacheTasks.Add(_cache.AddBuildngInfra(building.ProjectId, building));
            }
            else
            {
                _context.Buildings.Update(building);
                messages.Add("Building Updated");
                cacheTasks.Add(_cache.UpdateBuildngInfra(building.ProjectId, building));
            }

            responseData.building = building;
            projectIds.Add(building.ProjectId);
            _ = Task.Run(async () =>
            {
                // --- Push Notification Section ---
                // This section attempts to send a test push notification to the user's device.
                // It's designed to fail gracefully and handle invalid Firebase Cloud Messaging (FCM) tokens.

                var name = $"{loggedInEmployee.FirstName} {loggedInEmployee.LastName}";

                await _firebase.SendModifyBuildingMeaasgeAsync(building.Id, name, !isNew, tenantId);

            });
        }
        private void ProcessFloor(FloorDto dto, Guid tenantId, InfraVM responseData, List<string> messages, ISet<Guid> projectIds, List<Task> cacheTasks, IDictionary<Guid, Building> buildings,
            Employee loggedInEmployee)
        {
            using var scope = _serviceScopeFactory.CreateScope();
            var _firebase = scope.ServiceProvider.GetRequiredService<IFirebaseService>();

            Floor floor = _mapper.Map<Floor>(dto);
            floor.TenantId = tenantId;

            // Use the pre-fetched dictionary for parent lookup.
            Building? parentBuilding = buildings.TryGetValue(dto.BuildingId, out var b) ? b : null;

            bool isNew = dto.Id == null;
            if (isNew)
            {
                _context.Floor.Add(floor);
                messages.Add($"Floor Added in Building: {parentBuilding?.Name ?? "Unknown"}");
                cacheTasks.Add(_cache.AddBuildngInfra(parentBuilding?.ProjectId ?? Guid.Empty, floor: floor));
            }
            else
            {
                _context.Floor.Update(floor);
                messages.Add($"Floor Updated in Building: {parentBuilding?.Name ?? "Unknown"}");
                cacheTasks.Add(_cache.UpdateBuildngInfra(parentBuilding?.ProjectId ?? Guid.Empty, floor: floor));
            }

            responseData.floor = floor;
            if (parentBuilding != null) projectIds.Add(parentBuilding.ProjectId);

            _ = Task.Run(async () =>
            {
                // --- Push Notification Section ---
                // This section attempts to send a test push notification to the user's device.
                // It's designed to fail gracefully and handle invalid Firebase Cloud Messaging (FCM) tokens.

                var name = $"{loggedInEmployee.FirstName} {loggedInEmployee.LastName}";

                await _firebase.SendModifyFloorMeaasgeAsync(floor.Id, name, !isNew, tenantId);

            });
        }
        private void ProcessWorkArea(WorkAreaDto dto, Guid tenantId, InfraVM responseData, List<string> messages, ISet<Guid> projectIds, List<Task> cacheTasks, IDictionary<Guid, Floor> floors,
            Employee loggedInEmployee)
        {
            using var scope = _serviceScopeFactory.CreateScope();
            var _firebase = scope.ServiceProvider.GetRequiredService<IFirebaseService>();

            WorkArea workArea = _mapper.Map<WorkArea>(dto);
            workArea.TenantId = tenantId;

            // Use the pre-fetched dictionary for parent lookup.
            Floor? parentFloor = floors.TryGetValue(dto.FloorId, out var f) ? f : null;
            var parentBuilding = parentFloor?.Building;

            bool isNew = dto.Id == null;
            if (isNew)
            {
                _context.WorkAreas.Add(workArea);
                messages.Add($"Work Area Added in Building: {parentBuilding?.Name ?? "Unknown"}, on Floor: {parentFloor?.FloorName ?? "Unknown"}");
                cacheTasks.Add(_cache.AddBuildngInfra(parentBuilding?.ProjectId ?? Guid.Empty, workArea: workArea, buildingId: parentBuilding?.Id));
            }
            else
            {
                _context.WorkAreas.Update(workArea);
                messages.Add($"Work Area Updated in Building: {parentBuilding?.Name ?? "Unknown"}, on Floor: {parentFloor?.FloorName ?? "Unknown"}");
                cacheTasks.Add(_cache.UpdateBuildngInfra(parentBuilding?.ProjectId ?? Guid.Empty, workArea: workArea, buildingId: parentBuilding?.Id));
            }

            responseData.workArea = workArea;
            if (parentBuilding != null) projectIds.Add(parentBuilding.ProjectId);

            _ = Task.Run(async () =>
            {
                // --- Push Notification Section ---
                // This section attempts to send a test push notification to the user's device.
                // It's designed to fail gracefully and handle invalid Firebase Cloud Messaging (FCM) tokens.

                var name = $"{loggedInEmployee.FirstName} {loggedInEmployee.LastName}";

                await _firebase.SendModifyWorkAreaMeaasgeAsync(workArea.Id, name, !isNew, tenantId);

            });
        }
        private async Task<List<Guid>> GetPermissionIdsByProject(Guid projectId, Guid EmployeeId, Guid tenantId)
        {
            await using var context = await _dbContextFactory.CreateDbContextAsync();
            using var scope = _serviceScopeFactory.CreateScope();

            var _rolesHelper = scope.ServiceProvider.GetRequiredService<RolesHelper>();
            // 1. Try fetching permissions from cache (fast-path lookup).
            var featurePermissionIds = await _cache.GetPermissions(EmployeeId, tenantId);

            // If not found in cache, fallback to database (slower).
            if (featurePermissionIds == null)
            {
                var featurePermissions = await _rolesHelper.GetFeaturePermissionByEmployeeId(EmployeeId, tenantId);
                featurePermissionIds = featurePermissions.Select(fp => fp.Id).ToList();
            }

            // 2. Handle project-level permission overrides if a project is specified.
            if (projectId != Guid.Empty)
            {
                // Fetch permissions explicitly assigned to this employee in the project.
                var projectLevelPermissionIds = await context.ProjectLevelPermissionMappings
                    .Where(pl => pl.ProjectId == projectId && pl.EmployeeId == EmployeeId && pl.TenantId == tenantId)
                    .Select(pl => pl.PermissionId)
                    .ToListAsync();

                if (projectLevelPermissionIds?.Any() ?? false)
                {

                    // Define modules where project-level overrides apply.
                    var projectLevelModuleIds = new HashSet<Guid>
                    {
                        Guid.Parse("53176ebf-c75d-42e5-839f-4508ffac3def"),
                        Guid.Parse("9d4b5489-2079-40b9-bd77-6e1bf90bc19f"),
                        Guid.Parse("52c9cf54-1eb2-44d2-81bb-524cf29c0a94"),
                        Guid.Parse("a8cf4331-8f04-4961-8360-a3f7c3cc7462")
                    };

                    // Get all feature permissions under those modules where the user didn't have explicit project-level grants.
                    var allOverriddenPermissions = await context.FeaturePermissions
                        .Where(fp => projectLevelModuleIds.Contains(fp.FeatureId) &&
                                     !projectLevelPermissionIds.Contains(fp.Id))
                        .Select(fp => fp.Id)
                        .ToListAsync();

                    // Apply overrides:
                    // - Remove global permissions overridden by project-level rules.
                    // - Add explicit project-level permissions.
                    featurePermissionIds = featurePermissionIds
                        .Except(allOverriddenPermissions)       // Remove overridden
                        .Concat(projectLevelPermissionIds)      // Add project-level
                        .Distinct()                             // Ensure no duplicates
                        .ToList();
                }
            }
            return featurePermissionIds;
        }

        #endregion
    }
}