feat: user preferences support

src/app/api/v1/auth.py

@@ -13,6 +13,11 @@ from app.schemas.user import (
     UserCreate, UserResponse, UserUpdate, UserProfile,
     AdminOTPRequest, AdminRegistrationRequest
 )
+from app.schemas.user_preferences import (
+    UserPreferencesUpdate, UserPreferencesResponse,
+    DEFAULT_FAVORITE_APPS, AVAILABLE_APPS, DEFAULT_DASHBOARD_WIDGETS
+)
+from app.models.user_preference import UserPreference
 from app.models.user import User
 from app.core.supabase_auth import supabase_auth
 from app.services.audit_service import AuditService
@@ -794,3 +799,158 @@ async def logout(
     logger.info(f"User logged out: {current_user.email}")
     
     return MessageResponse(message="Logged out successfully")
+
+
+# ============================================
+# USER PREFERENCES ENDPOINTS
+# ============================================
+
+@router.get("/me/preferences", response_model=UserPreferencesResponse)
+async def get_my_preferences(
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get current user's preferences from user_preferences table
+    
+    Returns user preferences with role-based defaults if preferences don't exist yet.
+    Automatically creates preferences record if it doesn't exist (via database trigger).
+    """
+    # Get or create preferences
+    preferences = db.query(UserPreference).filter(
+        UserPreference.user_id == current_user.id,
+        UserPreference.deleted_at == None
+    ).first()
+    
+    # If no preferences exist, create with role-based defaults
+    if not preferences:
+        preferences = UserPreference(
+            user_id=current_user.id,
+            favorite_apps=DEFAULT_FAVORITE_APPS.get(current_user.role, ['dashboard', 'tickets', 'projects', 'maps']),
+            dashboard_widgets=DEFAULT_DASHBOARD_WIDGETS.get(current_user.role, ['recent_tickets', 'team_performance', 'sla_metrics']),
+            theme='light',
+            language='en'
+        )
+        db.add(preferences)
+        db.commit()
+        db.refresh(preferences)
+        logger.info(f"Created default preferences for user: {current_user.email}")
+    
+    return UserPreferencesResponse.from_orm(preferences)
+
+
+@router.put("/me/preferences", response_model=UserPreferencesResponse)
+async def update_my_preferences(
+    preferences_data: UserPreferencesUpdate,
+    request: Request,
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Update current user's preferences in user_preferences table
+    
+    Updates user preferences including favorite apps, theme, language, and notification settings.
+    Favorite apps are validated against role-specific available apps (max 6).
+    """
+    # Get or create preferences
+    preferences = db.query(UserPreference).filter(
+        UserPreference.user_id == current_user.id,
+        UserPreference.deleted_at == None
+    ).first()
+    
+    if not preferences:
+        # Create new preferences record
+        preferences = UserPreference(
+            user_id=current_user.id,
+            favorite_apps=DEFAULT_FAVORITE_APPS.get(current_user.role, []),
+            dashboard_widgets=DEFAULT_DASHBOARD_WIDGETS.get(current_user.role, [])
+        )
+        db.add(preferences)
+        db.flush()
+    
+    # Track changes for audit
+    changes = {'old': {}, 'new': {}}
+    
+    # Update only provided fields
+    update_data = preferences_data.dict(exclude_unset=True)
+    
+    # Validate favorite apps if provided
+    if 'favorite_apps' in update_data and update_data['favorite_apps'] is not None:
+        # Check max limit (6 apps)
+        if len(update_data['favorite_apps']) > 6:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Maximum 6 favorite apps allowed"
+            )
+        
+        # Validate against role-specific available apps
+        available_apps = AVAILABLE_APPS.get(current_user.role, [])
+        invalid_apps = [app for app in update_data['favorite_apps'] if app not in available_apps]
+        
+        if invalid_apps:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid apps for {current_user.role}: {', '.join(invalid_apps)}. "
+                       f"Available apps: {', '.join(available_apps)}"
+            )
+        
+        changes['old']['favorite_apps'] = preferences.favorite_apps
+        changes['new']['favorite_apps'] = update_data['favorite_apps']
+        preferences.favorite_apps = update_data['favorite_apps']
+    
+    # Update other fields
+    for field, value in update_data.items():
+        if field != 'favorite_apps' and value is not None:
+            old_value = getattr(preferences, field, None)
+            if old_value != value:
+                changes['old'][field] = old_value
+                changes['new'][field] = value
+                setattr(preferences, field, value)
+    
+    db.commit()
+    db.refresh(preferences)
+    
+    # Audit log
+    if changes['old']:
+        AuditService.log_action(
+            db=db,
+            action='update',
+            entity_type='user_preferences',
+            entity_id=str(preferences.id),
+            description=f"User updated preferences: {current_user.email}",
+            user=current_user,
+            request=request,
+            changes=changes
+        )
+    
+    logger.info(f"Preferences updated for user: {current_user.email}")
+    
+    return UserPreferencesResponse.from_orm(preferences)
+
+
+@router.get("/me/preferences/available-apps", response_model=dict)
+async def get_available_apps(
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get list of apps available for user to favorite based on their role
+    
+    Returns currently favorited apps, all available apps for the role,
+    and role-based default favorites.
+    """
+    # Get current preferences
+    preferences = db.query(UserPreference).filter(
+        UserPreference.user_id == current_user.id,
+        UserPreference.deleted_at == None
+    ).first()
+    
+    current_favorites = preferences.favorite_apps if preferences else DEFAULT_FAVORITE_APPS.get(current_user.role, [])
+    
+    return {
+        "role": current_user.role,
+        "current_favorites": current_favorites,
+        "available_apps": AVAILABLE_APPS.get(current_user.role, []),
+        "default_favorites": DEFAULT_FAVORITE_APPS.get(current_user.role, []),
+        "max_favorites": 6
+    }

src/app/models/user_preference.py

@@ -0,0 +1,54 @@
+"""
+User Preferences Model
+Stores user-specific UI preferences, favorites, theme, and settings
+"""
+from sqlalchemy import Column, String, Boolean, Integer, Float, ForeignKey, ARRAY, Text
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+from app.models.base import BaseModel
+
+
+class UserPreference(BaseModel):
+    """
+    User Preferences model - One row per user
+    Stores UI preferences, favorites, theme, and settings
+    """
+    __tablename__ = "user_preferences"
+    
+    # Link to user
+    user_id = Column(UUID(as_uuid=True), ForeignKey('users.id', ondelete='CASCADE'), nullable=False, unique=True)
+    
+    # Favorite Apps (for 9-dot app launcher)
+    # Array of app codes that appear in the top navigation bar
+    # Max: 6 favorites (enforced in application logic)
+    favorite_apps = Column(ARRAY(Text), default=['dashboard', 'tickets', 'projects', 'maps'])
+    
+    # UI Preferences
+    theme = Column(String(50), default='light')  # 'light', 'dark', 'auto'
+    language = Column(String(10), default='en')  # 'en', 'sw' (Swahili), 'fr', etc.
+    
+    # Notification Preferences
+    email_notifications = Column(Boolean, default=True)
+    push_notifications = Column(Boolean, default=True)
+    sms_notifications = Column(Boolean, default=False)
+    
+    # Dashboard Layout (which widgets to show)
+    # Array of widget codes: ['recent_tickets', 'team_performance', 'sla_metrics', 'map_view']
+    dashboard_widgets = Column(ARRAY(Text), default=['recent_tickets', 'team_performance', 'sla_metrics'])
+    
+    # Table/List Preferences
+    default_tickets_view = Column(String(50), default='list')  # 'list', 'kanban', 'calendar'
+    tickets_per_page = Column(Integer, default=25)  # Pagination size
+    default_sort_field = Column(String(100), default='created_at')  # Default sort field
+    default_sort_order = Column(String(10), default='desc')  # 'asc', 'desc'
+    
+    # Map Preferences (for field agents and dispatchers)
+    default_map_zoom = Column(Integer, default=12)
+    default_map_center_lat = Column(Float, nullable=True)  # User's preferred map center
+    default_map_center_lng = Column(Float, nullable=True)
+    
+    # Additional settings (flexible JSONB for future expansion)
+    # Can store: sidebar_collapsed, compact_mode, color_blind_mode, etc.
+    additional_settings = Column(JSONB, default={})
+    
+    def __repr__(self):
+        return f"<UserPreference(user_id='{self.user_id}', theme='{self.theme}')>"

src/app/schemas/user_preferences.py

@@ -0,0 +1,207 @@
+"""
+User Preferences Schemas
+Handles user-specific settings like favorite apps, theme, notifications, etc.
+Maps to user_preferences table in database
+"""
+from pydantic import BaseModel, Field, validator
+from typing import Optional, List, Dict, Any
+from uuid import UUID
+
+
+class UserPreferencesUpdate(BaseModel):
+    """Update user preferences"""
+    favorite_apps: Optional[List[str]] = Field(
+        None,
+        max_items=6,
+        description="List of favorite app codes (max 6) e.g., ['dashboard', 'tickets', 'projects']"
+    )
+    theme: Optional[str] = Field(
+        None,
+        description="UI theme: 'light', 'dark', 'auto'"
+    )
+    language: Optional[str] = Field(
+        None,
+        description="Preferred language code (e.g., 'en', 'sw')"
+    )
+    email_notifications: Optional[bool] = Field(
+        None,
+        description="Enable/disable email notifications"
+    )
+    push_notifications: Optional[bool] = Field(
+        None,
+        description="Enable/disable push notifications"
+    )
+    sms_notifications: Optional[bool] = Field(
+        None,
+        description="Enable/disable SMS notifications"
+    )
+    dashboard_widgets: Optional[List[str]] = Field(
+        None,
+        description="Array of widget codes to display on dashboard"
+    )
+    default_tickets_view: Optional[str] = Field(
+        None,
+        description="Default view for tickets: 'list', 'kanban', 'calendar'"
+    )
+    tickets_per_page: Optional[int] = Field(
+        None,
+        ge=10,
+        le=100,
+        description="Pagination size (10-100)"
+    )
+    default_sort_field: Optional[str] = Field(
+        None,
+        description="Default sort field"
+    )
+    default_sort_order: Optional[str] = Field(
+        None,
+        description="Default sort order: 'asc', 'desc'"
+    )
+    default_map_zoom: Optional[int] = Field(
+        None,
+        description="Default map zoom level"
+    )
+    default_map_center_lat: Optional[float] = Field(
+        None,
+        description="Default map center latitude"
+    )
+    default_map_center_lng: Optional[float] = Field(
+        None,
+        description="Default map center longitude"
+    )
+    additional_settings: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Additional settings (sidebar_collapsed, compact_mode, etc.)"
+    )
+    
+    @validator('theme')
+    def validate_theme(cls, v):
+        if v and v not in ['light', 'dark', 'auto']:
+            raise ValueError('Theme must be one of: light, dark, auto')
+        return v
+    
+    @validator('default_tickets_view')
+    def validate_tickets_view(cls, v):
+        if v and v not in ['list', 'kanban', 'calendar']:
+            raise ValueError('Tickets view must be one of: list, kanban, calendar')
+        return v
+    
+    @validator('default_sort_order')
+    def validate_sort_order(cls, v):
+        if v and v not in ['asc', 'desc']:
+            raise ValueError('Sort order must be: asc or desc')
+        return v
+
+
+class UserPreferencesResponse(BaseModel):
+    """User preferences response"""
+    id: UUID
+    user_id: UUID
+    favorite_apps: List[str] = Field(
+        default_factory=lambda: ['dashboard', 'tickets', 'projects', 'maps'],
+        description="List of favorite app codes"
+    )
+    theme: str = Field(default="light", description="UI theme")
+    language: str = Field(default="en", description="Preferred language")
+    email_notifications: bool = Field(default=True, description="Email notifications enabled")
+    push_notifications: bool = Field(default=True, description="Push notifications enabled")
+    sms_notifications: bool = Field(default=False, description="SMS notifications enabled")
+    dashboard_widgets: List[str] = Field(
+        default_factory=lambda: ['recent_tickets', 'team_performance', 'sla_metrics'],
+        description="Dashboard widgets"
+    )
+    default_tickets_view: str = Field(default="list", description="Default tickets view")
+    tickets_per_page: int = Field(default=25, description="Tickets per page")
+    default_sort_field: str = Field(default="created_at", description="Default sort field")
+    default_sort_order: str = Field(default="desc", description="Default sort order")
+    default_map_zoom: int = Field(default=12, description="Default map zoom")
+    default_map_center_lat: Optional[float] = Field(None, description="Map center latitude")
+    default_map_center_lng: Optional[float] = Field(None, description="Map center longitude")
+    additional_settings: Dict[str, Any] = Field(default_factory=dict, description="Additional settings")
+    
+    class Config:
+        from_attributes = True
+        json_schema_extra = {
+            "example": {
+                "id": "550e8400-e29b-41d4-a716-446655440000",
+                "user_id": "550e8400-e29b-41d4-a716-446655440001",
+                "favorite_apps": ["dashboard", "organizations", "users", "activity"],
+                "theme": "light",
+                "language": "en",
+                "email_notifications": True,
+                "push_notifications": True,
+                "sms_notifications": False,
+                "dashboard_widgets": ["recent_tickets", "team_performance", "sla_metrics"],
+                "default_tickets_view": "list",
+                "tickets_per_page": 25,
+                "default_sort_field": "created_at",
+                "default_sort_order": "desc",
+                "default_map_zoom": 12,
+                "default_map_center_lat": None,
+                "default_map_center_lng": None,
+                "additional_settings": {}
+            }
+        }
+
+
+# Default favorite apps by role (using database app codes - lowercase with underscores)
+DEFAULT_FAVORITE_APPS = {
+    "platform_admin": ["dashboard", "organizations", "users", "activity"],
+    "client_admin": ["dashboard", "projects", "tickets", "team"],
+    "contractor_admin": ["dashboard", "projects", "tickets", "team"],
+    "sales_manager": ["dashboard", "sales_orders", "customers", "reports"],
+    "project_manager": ["dashboard", "projects", "tickets", "team"],
+    "dispatcher": ["dashboard", "tickets", "maps", "team"],
+    "field_agent": ["tickets", "maps", "timesheets", "profile"],
+    "sales_agent": ["dashboard", "sales_orders", "customers", "maps"]
+}
+
+# Available apps by role (what they can favorite - max 6)
+AVAILABLE_APPS = {
+    "platform_admin": [
+        # Core apps
+        "dashboard", "organizations", "users", "activity",
+        # Management
+        "settings", "billing", "notifications", "help"
+    ],
+    "client_admin": [
+        "dashboard", "projects", "tickets", "team", "sales_orders",
+        "customers", "contractors", "reports", "settings", "help"
+    ],
+    "contractor_admin": [
+        "dashboard", "projects", "tickets", "team", "timesheets",
+        "payroll", "reports", "settings", "help"
+    ],
+    "sales_manager": [
+        "dashboard", "sales_orders", "customers", "reports",
+        "team", "maps", "settings", "help"
+    ],
+    "project_manager": [
+        "dashboard", "projects", "tickets", "team", "reports",
+        "maps", "settings", "help"
+    ],
+    "dispatcher": [
+        "dashboard", "tickets", "maps", "team", "projects",
+        "reports", "settings", "help"
+    ],
+    "field_agent": [
+        "tickets", "maps", "timesheets", "profile", "expenses",
+        "documents", "help"
+    ],
+    "sales_agent": [
+        "dashboard", "sales_orders", "customers", "maps",
+        "profile", "reports", "help"
+    ]
+}
+
+# Available dashboard widgets by role
+DEFAULT_DASHBOARD_WIDGETS = {
+    "platform_admin": ["recent_tickets", "team_performance", "sla_metrics", "organizations_overview"],
+    "client_admin": ["recent_tickets", "team_performance", "sla_metrics", "project_status"],
+    "contractor_admin": ["recent_tickets", "team_performance", "payroll_summary", "project_status"],
+    "sales_manager": ["sales_pipeline", "revenue_metrics", "team_performance", "conversion_rates"],
+    "project_manager": ["project_status", "team_performance", "sla_metrics", "map_view"],
+    "dispatcher": ["recent_tickets", "map_view", "team_availability", "sla_metrics"],
+    "field_agent": ["my_tickets", "earnings_summary", "attendance_summary"],
+    "sales_agent": ["my_sales", "customer_pipeline", "earnings_summary"]
+}