add unified project overview endpoint with caching and role-based response

docs/api/projects/project-overview.md

@@ -0,0 +1,237 @@
+# Project Overview Endpoint
+
+## Purpose
+
+Single endpoint that replaces 4 separate calls to get complete project structure. Returns project details, regions, roles, subcontractors, and team info based on user permissions.
+
+**Replaces:**
+- `GET /projects/{id}`
+- `GET /projects/{id}/regions`
+- `GET /projects/{id}/project-roles`
+- `GET /projects/{id}/subcontractors`
+
+## Endpoint
+
+```
+GET /api/v1/projects/{project_id}/overview
+```
+
+**Query Params:**
+- `refresh` (optional): `true` to force cache refresh
+
+**Cache:** 12 hours
+
+## Response Structure
+
+### For Managers/Admins
+
+```json
+{
+  "project": {
+    "id": "uuid",
+    "title": "Project Name",
+    "project_type": "customer_service",
+    "status": "active",
+    "client_id": "uuid",
+    "client_name": "Client Name",
+    "contractor_id": "uuid",
+    "contractor_name": "Contractor Name",
+    "primary_manager_id": "uuid",
+    "primary_manager_name": "Manager Name",
+    "service_type": "ftth",
+    "planned_start_date": "2025-01-01",
+    "planned_end_date": "2025-12-31",
+    "activation_requirements": [...],
+    "photo_requirements": [...],
+    "budget": {...},
+    "is_closed": false,
+    "created_at": "2025-01-01T00:00:00Z"
+  },
+  "regions": [
+    {
+      "id": "uuid",
+      "region_name": "Nairobi West",
+      "region_code": "NRB-W",
+      "manager_id": "uuid",
+      "manager_name": "Regional Manager",
+      "is_active": true,
+      "city": "Nairobi",
+      "latitude": -1.2921,
+      "longitude": 36.8219
+    }
+  ],
+  "roles": [
+    {
+      "id": "uuid",
+      "role_name": "Technician",
+      "compensation_type": "commission",
+      "commission_percentage": 15.0,
+      "base_amount": 500.0,
+      "is_active": true
+    }
+  ],
+  "subcontractors": [
+    {
+      "id": "uuid",
+      "subcontractor_id": "uuid",
+      "subcontractor_name": "SubCo Ltd",
+      "scope_description": "Installation work",
+      "project_region_id": "uuid",
+      "region_name": "Nairobi West",
+      "contract_value": 50000.0,
+      "is_active": true
+    }
+  ],
+  "team_summary": {
+    "total_members": 25,
+    "by_role": {
+      "field_agent": 15,
+      "dispatcher": 3,
+      "sales_agent": 5,
+      "project_manager": 2
+    },
+    "by_region": {
+      "Nairobi West": 10,
+      "Mombasa": 8,
+      "Project-wide": 7
+    }
+  },
+  "my_involvement": null,
+  "cached_at": "2025-12-02T10:00:00Z",
+  "cache_expires_in_seconds": 43200
+}
+```
+
+### For Field Agents/Sales Agents
+
+```json
+{
+  "project": {
+    "id": "uuid",
+    "title": "Project Name",
+    "project_type": "customer_service",
+    "status": "active",
+    "client_name": "Client Name",
+    "contractor_name": "Contractor Name",
+    "service_type": "ftth",
+    "activation_requirements": [...],
+    "photo_requirements": [...]
+  },
+  "regions": [
+    {
+      "id": "uuid",
+      "region_name": "Nairobi West",
+      "is_active": true,
+      "city": "Nairobi"
+    }
+  ],
+  "roles": null,
+  "subcontractors": null,
+  "team_summary": null,
+  "my_involvement": {
+    "user_id": "uuid",
+    "user_name": "John Doe",
+    "user_email": "john@example.com",
+    "user_role": "field_agent",
+    "team_role": "technician",
+    "project_role_id": "uuid",
+    "project_role_name": "Senior Technician",
+    "assigned_region_id": "uuid",
+    "assigned_region_name": "Nairobi West",
+    "is_lead": false,
+    "assigned_at": "2025-01-15T08:00:00Z",
+    "subcontractor_id": null,
+    "subcontractor_name": null
+  },
+  "cached_at": "2025-12-02T10:00:00Z",
+  "cache_expires_in_seconds": 43200
+}
+```
+
+## Frontend Usage
+
+### Display Project Overview Page
+
+```typescript
+// Fetch overview
+const response = await fetch(`/api/v1/projects/${projectId}/overview`);
+const data = await response.json();
+
+// Show project header
+showProjectHeader({
+  title: data.project.title,
+  status: data.project.status,
+  client: data.project.client_name,
+  contractor: data.project.contractor_name
+});
+
+// Show regions (all users see all regions)
+data.regions.forEach(region => {
+  const isMyRegion = data.my_involvement?.assigned_region_id === region.id;
+  renderRegionCard(region, isMyRegion); // Highlight user's region
+});
+
+// Role-specific rendering
+if (data.my_involvement) {
+  // Field agent/sales agent view
+  showMyInvolvement({
+    role: data.my_involvement.team_role,
+    region: data.my_involvement.assigned_region_name,
+    projectRole: data.my_involvement.project_role_name
+  });
+} else {
+  // Manager/admin view
+  showRoles(data.roles);
+  showSubcontractors(data.subcontractors);
+  showTeamSummary(data.team_summary);
+}
+```
+
+### Check User's Region Assignment
+
+```typescript
+// Highlight user's assigned region in UI
+const myRegionId = data.my_involvement?.assigned_region_id;
+
+data.regions.forEach(region => {
+  const card = createRegionCard(region);
+  if (region.id === myRegionId) {
+    card.classList.add('my-region', 'highlighted');
+  }
+});
+```
+
+### Display Requirements (Field Agents)
+
+```typescript
+// Show what photos are required
+data.project.photo_requirements.forEach(req => {
+  console.log(`${req.type}: ${req.min_photos}-${req.max_photos} photos`);
+});
+
+// Show activation form fields
+data.project.activation_requirements.forEach(field => {
+  renderFormField({
+    name: field.field,
+    label: field.label,
+    type: field.type,
+    required: field.required,
+    options: field.options
+  });
+});
+```
+
+## Key Points
+
+1. **Single call** - Replaces 4 separate API calls
+2. **Role-based** - Response adapts to user permissions automatically
+3. **Long cache** - 12 hours (structure rarely changes)
+4. **All see regions** - Everyone sees all regions, UI highlights user's assigned region
+5. **Field agents** - See their involvement only, not other team members
+6. **Managers** - See complete project structure and team composition
+
+## Error Responses
+
+- `404` - Project not found
+- `403` - User not authorized to access project
+- `500` - Server error

src/app/api/v1/projects.py

@@ -475,6 +475,63 @@ async def get_project_activity_feed(
         )
 
 
+@router.get("/{project_id}/overview")
+async def get_project_overview(
+    project_id: UUID,
+    refresh: bool = Query(False, description="Force refresh cache"),
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get comprehensive project overview (structure, not metrics).
+    
+    Returns project details, regions, roles, subcontractors, and team information
+    tailored to the user's role and permissions.
+    
+    **For Managers/Admins:**
+    - Full project details
+    - All regions with details
+    - All project roles with compensation structures
+    - All subcontractors
+    - Team composition summary
+    
+    **For Field Agents/Sales Agents:**
+    - Basic project information
+    - All regions (UI highlights their assigned region)
+    - Their specific involvement (role, region, subcontractor)
+    - Project requirements (photo_requirements, activation_requirements)
+    - No access to other team members, all roles, or all subcontractors
+    
+    **Performance:**
+    - Cached for 12 hours for optimal performance
+    - Use ?refresh=true to force cache refresh
+    - Structure changes rarely, so long cache is appropriate
+    
+    **Authorization:** Any user with project access
+    """
+    try:
+        from app.services.dashboard_service import DashboardService
+        from app.schemas.project import ProjectOverviewResponse
+        
+        overview = DashboardService.get_project_overview(
+            db=db,
+            project_id=str(project_id),
+            current_user=current_user,
+            force_refresh=refresh
+        )
+        
+        return overview
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get project overview: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to get project overview: {str(e)}"
+        )
+
+
 @router.put("/{project_id}", response_model=ProjectResponse)
 @router.patch("/{project_id}", response_model=ProjectResponse)
 @require_permission("manage_projects")

src/app/schemas/project.py

@@ -534,3 +534,54 @@ class ProjectSetupResponse(BaseModel):
     subcontractors_added: int
     team_members_added: int
     message: str
+
+
+# ============================================
+# PROJECT OVERVIEW SCHEMAS
+# ============================================
+
+class UserInvolvement(BaseModel):
+    """User's involvement in the project (for field agents/sales agents)"""
+    user_id: UUID
+    user_name: str
+    user_email: Optional[str]
+    user_role: str  # System role (field_agent, sales_agent, etc.)
+    team_role: Optional[str]  # Project team role
+    project_role_id: Optional[UUID]  # Custom project role with compensation
+    project_role_name: Optional[str]
+    assigned_region_id: Optional[UUID]  # Their assigned region
+    assigned_region_name: Optional[str]
+    is_lead: bool
+    assigned_at: datetime
+    subcontractor_id: Optional[UUID]  # If they work for a subcontractor
+    subcontractor_name: Optional[str]
+
+
+class ProjectOverviewResponse(BaseModel):
+    """
+    Comprehensive project overview response.
+    Adapts based on user role:
+    - Managers/Admins: Full project structure
+    - Field/Sales Agents: Basic info + their involvement
+    """
+    # Basic project info (everyone sees this)
+    project: ProjectResponse
+    
+    # Regions (everyone sees all regions)
+    regions: List[ProjectRegionResponse]
+    
+    # Role-specific data
+    # For managers/admins: all roles, all subcontractors, team composition
+    roles: Optional[List[ProjectRoleResponse]] = None
+    subcontractors: Optional[List[ProjectSubcontractorResponse]] = None
+    team_summary: Optional[Dict[str, Any]] = None  # Team composition stats
+    
+    # For field/sales agents: their involvement only
+    my_involvement: Optional[UserInvolvement] = None
+    
+    # Cache info
+    cached_at: str = Field(..., description="ISO timestamp when data was cached")
+    cache_expires_in_seconds: int = Field(43200, description="Cache TTL in seconds (12 hours)")
+    
+    class Config:
+        from_attributes = True

src/app/services/dashboard_service.py

@@ -25,7 +25,7 @@ from app.models.enums import ProjectType, AppRole, TicketStatus, SalesOrderStatu
 from app.services.ticket_service import TicketService
 from app.services.sales_order_service import SalesOrderService
 from app.services.notification_service import NotificationService
-from app.utils.cache import get_cached_dashboard, set_cached_dashboard
+from app.utils.cache import get_cached_dashboard, set_cached_dashboard, get_cached_overview, set_cached_overview
 
 logger = logging.getLogger(__name__)
 
@@ -1326,3 +1326,220 @@ class DashboardService:
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail=f"Failed to generate user overview: {str(e)}"
             )
+
+    @staticmethod
+    def get_project_overview(
+        db: Session,
+        project_id: str,
+        current_user: User,
+        force_refresh: bool = False
+    ) -> Dict:
+        """
+        Get comprehensive project overview (structure, not metrics).
+        
+        Returns project details, regions, roles, subcontractors, and team info
+        based on user's role and permissions.
+        
+        Uses caching with 12-hour TTL unless force_refresh=True.
+        
+        Args:
+            db: Database session
+            project_id: Project UUID
+            current_user: Current authenticated user
+            force_refresh: Force cache refresh
+            
+        Returns:
+            Dict with project overview data tailored to user role
+        """
+        # Check cache first (unless force refresh)
+        if not force_refresh:
+            cached = get_cached_overview(project_id, str(current_user.id))
+            if cached:
+                logger.info(f"Overview cache HIT for project {project_id}, user {current_user.id}")
+                return cached
+        
+        logger.info(f"Overview cache MISS for project {project_id}, user {current_user.id} - building fresh data")
+        
+        # Get project with relationships
+        project = db.query(Project).options(
+            joinedload(Project.client),
+            joinedload(Project.contractor),
+            joinedload(Project.primary_manager)
+        ).filter(
+            Project.id == project_id,
+            Project.deleted_at.is_(None)
+        ).first()
+        
+        if not project:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Project not found: {project_id}"
+            )
+        
+        # Check authorization
+        if not DashboardService.can_user_access_project(current_user, project_id, db):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Not authorized to access this project"
+            )
+        
+        # Build project response
+        from app.schemas.project import ProjectResponse
+        project_response = ProjectResponse.model_validate(project)
+        project_response.client_name = project.client.name if project.client else None
+        project_response.contractor_name = project.contractor.name if project.contractor else None
+        project_response.primary_manager_name = project.primary_manager.name if project.primary_manager else None
+        project_response.is_overdue = project.is_overdue
+        project_response.duration_days = project.duration_days
+        
+        # Get all regions (everyone sees all regions)
+        from app.models.project import ProjectRegion
+        from app.schemas.project import ProjectRegionResponse
+        
+        regions = db.query(ProjectRegion).options(
+            joinedload(ProjectRegion.manager)
+        ).filter(
+            ProjectRegion.project_id == project_id,
+            ProjectRegion.deleted_at.is_(None)
+        ).all()
+        
+        region_responses = []
+        for region in regions:
+            region_resp = ProjectRegionResponse.model_validate(region)
+            region_resp.manager_name = region.manager.name if region.manager else None
+            region_responses.append(region_resp)
+        
+        # Build response based on user role
+        is_manager_or_admin = current_user.role in [
+            AppRole.PLATFORM_ADMIN.value,
+            AppRole.CLIENT_ADMIN.value,
+            AppRole.CONTRACTOR_ADMIN.value,
+            AppRole.PROJECT_MANAGER.value,
+            AppRole.DISPATCHER.value
+        ]
+        
+        overview_data = {
+            "project": project_response.model_dump(),
+            "regions": [r.model_dump() for r in region_responses],
+            "cached_at": datetime.utcnow().isoformat() + "Z",
+            "cache_expires_in_seconds": 43200  # 12 hours
+        }
+        
+        if is_manager_or_admin:
+            # Managers/Admins: Get full project structure
+            
+            # Get all project roles
+            from app.models.project import ProjectRole
+            from app.schemas.project import ProjectRoleResponse
+            
+            roles = db.query(ProjectRole).filter(
+                ProjectRole.project_id == project_id,
+                ProjectRole.deleted_at.is_(None)
+            ).all()
+            
+            role_responses = [ProjectRoleResponse.model_validate(r) for r in roles]
+            overview_data["roles"] = [r.model_dump() for r in role_responses]
+            
+            # Get all subcontractors
+            from app.models.project import ProjectSubcontractor
+            from app.schemas.project import ProjectSubcontractorResponse
+            
+            subcontractors = db.query(ProjectSubcontractor).options(
+                joinedload(ProjectSubcontractor.subcontractor),
+                joinedload(ProjectSubcontractor.region)
+            ).filter(
+                ProjectSubcontractor.project_id == project_id,
+                ProjectSubcontractor.deleted_at.is_(None)
+            ).all()
+            
+            subcontractor_responses = []
+            for sub in subcontractors:
+                sub_resp = ProjectSubcontractorResponse.model_validate(sub)
+                sub_resp.subcontractor_name = sub.subcontractor.name if sub.subcontractor else None
+                sub_resp.region_name = sub.region.region_name if sub.region else None
+                subcontractor_responses.append(sub_resp)
+            
+            overview_data["subcontractors"] = [s.model_dump() for s in subcontractor_responses]
+            
+            # Get team summary
+            team_members = db.query(ProjectTeam).options(
+                joinedload(ProjectTeam.user),
+                joinedload(ProjectTeam.project_role),
+                joinedload(ProjectTeam.region)
+            ).filter(
+                ProjectTeam.project_id == project_id,
+                ProjectTeam.deleted_at.is_(None),
+                ProjectTeam.removed_at.is_(None)
+            ).all()
+            
+            # Build team summary
+            by_role = {}
+            by_region = {}
+            for member in team_members:
+                # Count by system role
+                user_role = member.user.role if member.user else "unknown"
+                by_role[user_role] = by_role.get(user_role, 0) + 1
+                
+                # Count by region
+                if member.region:
+                    region_name = member.region.region_name
+                    by_region[region_name] = by_region.get(region_name, 0) + 1
+                else:
+                    by_region["Project-wide"] = by_region.get("Project-wide", 0) + 1
+            
+            overview_data["team_summary"] = {
+                "total_members": len(team_members),
+                "by_role": by_role,
+                "by_region": by_region
+            }
+            
+            overview_data["my_involvement"] = None
+            
+        else:
+            # Field agents/Sales agents: Get their involvement only
+            team_membership = db.query(ProjectTeam).options(
+                joinedload(ProjectTeam.project_role),
+                joinedload(ProjectTeam.region),
+                joinedload(ProjectTeam.subcontractor).joinedload(ProjectSubcontractor.subcontractor)
+            ).filter(
+                ProjectTeam.project_id == project_id,
+                ProjectTeam.user_id == current_user.id,
+                ProjectTeam.deleted_at.is_(None),
+                ProjectTeam.removed_at.is_(None)
+            ).first()
+            
+            if team_membership:
+                involvement = {
+                    "user_id": str(current_user.id),
+                    "user_name": current_user.name,
+                    "user_email": current_user.email,
+                    "user_role": current_user.role,
+                    "team_role": team_membership.role,
+                    "project_role_id": str(team_membership.project_role_id) if team_membership.project_role_id else None,
+                    "project_role_name": team_membership.project_role.role_name if team_membership.project_role else None,
+                    "assigned_region_id": str(team_membership.project_region_id) if team_membership.project_region_id else None,
+                    "assigned_region_name": team_membership.region.region_name if team_membership.region else None,
+                    "is_lead": team_membership.is_lead,
+                    "assigned_at": team_membership.assigned_at.isoformat() if team_membership.assigned_at else None,
+                    "subcontractor_id": str(team_membership.project_subcontractor_id) if team_membership.project_subcontractor_id else None,
+                    "subcontractor_name": None
+                }
+                
+                # Get subcontractor name if applicable
+                if team_membership.subcontractor and team_membership.subcontractor.subcontractor:
+                    involvement["subcontractor_name"] = team_membership.subcontractor.subcontractor.name
+                
+                overview_data["my_involvement"] = involvement
+            else:
+                overview_data["my_involvement"] = None
+            
+            # Don't include roles, subcontractors, or team_summary for field agents
+            overview_data["roles"] = None
+            overview_data["subcontractors"] = None
+            overview_data["team_summary"] = None
+        
+        # Cache the result
+        set_cached_overview(project_id, str(current_user.id), overview_data)
+        
+        logger.info(f"Built and cached overview for project {project_id}")
+        return overview_data

src/app/utils/cache.py

@@ -20,6 +20,11 @@ dashboard_cache_lock = RLock()
 trends_cache = TTLCache(maxsize=500, ttl=600)
 trends_cache_lock = RLock()
 
+# Project overview cache with 12-hour TTL (structure changes rarely)
+# Stores project structure: regions, roles, subcontractors, team info
+overview_cache = TTLCache(maxsize=500, ttl=43200)  # 12 hours = 43200 seconds
+overview_cache_lock = RLock()
+
 
 def get_cached_dashboard(project_id: str, user_id: str) -> Optional[dict]:
     """
@@ -180,6 +185,71 @@ def clear_all_caches() -> None:
         logger.error(f"Error clearing caches: {e}")
 
 
+def get_cached_overview(project_id: str, user_id: str) -> Optional[dict]:
+    """
+    Get cached project overview data.
+    
+    Args:
+        project_id: UUID of the project
+        user_id: UUID of the user
+        
+    Returns:
+        Cached overview dict or None if not found/expired
+    """
+    try:
+        with overview_cache_lock:
+            key = f"overview:{project_id}:{user_id}"
+            cached_data = overview_cache.get(key)
+            if cached_data:
+                logger.debug(f"Overview cache HIT: {key}")
+            return cached_data
+    except Exception as e:
+        logger.error(f"Error retrieving overview from cache: {e}")
+        return None
+
+
+def set_cached_overview(project_id: str, user_id: str, data: dict) -> None:
+    """
+    Cache project overview data.
+    
+    Args:
+        project_id: UUID of the project
+        user_id: UUID of the user
+        data: Overview data to cache
+    """
+    try:
+        with overview_cache_lock:
+            key = f"overview:{project_id}:{user_id}"
+            overview_cache[key] = data
+            logger.debug(f"Overview cache SET: {key}")
+    except Exception as e:
+        logger.error(f"Error setting overview cache: {e}")
+
+
+def invalidate_overview_cache(project_id: str) -> None:
+    """
+    Invalidate all cached overviews for a project.
+    Called when project structure changes (regions, roles, team, subcontractors).
+    
+    Args:
+        project_id: UUID of the project
+    """
+    try:
+        with overview_cache_lock:
+            keys_to_delete = [
+                k for k in overview_cache.keys() 
+                if k.startswith(f"overview:{project_id}:")
+            ]
+            
+            for key in keys_to_delete:
+                overview_cache.pop(key, None)
+                
+            if keys_to_delete:
+                logger.info(f"Invalidated {len(keys_to_delete)} overview cache entries for project {project_id}")
+    except Exception as e:
+        logger.error(f"Error invalidating overview cache: {e}")
+
+
 def get_cache_stats() -> dict:
     """
     Get cache statistics for monitoring.
@@ -188,7 +258,7 @@ def get_cache_stats() -> dict:
         Dict with cache size, hits, etc.
     """
     try:
-        with dashboard_cache_lock, trends_cache_lock:
+        with dashboard_cache_lock, trends_cache_lock, overview_cache_lock:
             return {
                 "dashboard_cache": {
                     "size": len(dashboard_cache),
@@ -199,6 +269,11 @@ def get_cache_stats() -> dict:
                     "size": len(trends_cache),
                     "maxsize": trends_cache.maxsize,
                     "ttl": trends_cache.ttl
+                },
+                "overview_cache": {
+                    "size": len(overview_cache),
+                    "maxsize": overview_cache.maxsize,
+                    "ttl": overview_cache.ttl
                 }
             }
     except Exception as e: