# Copyright (c) 2025 Patrick Motsch
# All rights reserved.
"""
Feature management routes for the backend API.
Implements endpoints for Feature and FeatureInstance management.

Multi-Tenant Design:
- Feature definitions are global (SysAdmin can manage)
- FeatureInstances belong to mandates (Mandate Admin can manage)
- Template roles are copied on instance creation
"""

from fastapi import APIRouter, HTTPException, Depends, Request, Query
from typing import List, Dict, Any, Optional
from fastapi import status
import logging
from pydantic import BaseModel, Field

from modules.auth import limiter, getRequestContext, RequestContext, requireSysAdminRole
from modules.datamodels.datamodelUam import User, UserInDB
from modules.datamodels.datamodelFeatures import Feature, FeatureInstance
from modules.interfaces.interfaceDbApp import getRootInterface
from modules.interfaces.interfaceFeatures import getFeatureInterface
from modules.security.rbacCatalog import getCatalogService

logger = logging.getLogger(__name__)

router = APIRouter(
    prefix="/api/features",
    tags=["Features"],
    responses={404: {"description": "Not found"}}
)


# =============================================================================
# Request/Response Models
# =============================================================================

class FeatureInstanceCreate(BaseModel):
    """Request model for creating a feature instance"""
    featureCode: str = Field(..., description="Feature code (e.g., 'trustee', 'chatbot')")
    label: str = Field(..., description="Instance label (e.g., 'Buchhaltung 2025')")
    enabled: bool = Field(True, description="Whether this feature instance is enabled")
    copyTemplateRoles: bool = Field(True, description="Whether to copy template roles on creation")
    config: Optional[Dict[str, Any]] = Field(None, description="Instance-specific configuration (JSONB). Structure depends on featureCode.")


class FeatureInstanceResponse(BaseModel):
    """Response model for feature instance"""
    id: str
    featureCode: str
    mandateId: str
    label: str
    enabled: bool


class SyncRolesResult(BaseModel):
    """Response model for role synchronization"""
    added: int
    removed: int
    unchanged: int


# =============================================================================
# Feature Endpoints (Global - mostly read-only for non-SysAdmin)
# =============================================================================

@router.get("/", response_model=List[Dict[str, Any]])
@limiter.limit("60/minute")
def list_features(
    request: Request,
    context: RequestContext = Depends(getRequestContext)
) -> List[Dict[str, Any]]:
    """
    List all available features.
    
    Returns global feature definitions from the RBAC Catalog.
    Features are automatically registered at startup from feature containers.
    Any authenticated user can see available features.
    """
    try:
        # Features come from the RBAC Catalog (registered at startup from feature containers)
        # NOT from the database - features are code-defined, not user-created
        catalogService = getCatalogService()
        features = catalogService.getFeatureDefinitions()
        return features
        
    except Exception as e:
        logger.error(f"Error listing features: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to list features: {str(e)}"
        )


# =============================================================================
# My Feature Instances (No mandate context needed)
# IMPORTANT: Must be before /{featureCode} to avoid route matching conflict
# =============================================================================

class FeaturesMyResponse(BaseModel):
    """Hierarchical response for GET /features/my"""
    mandates: List[Dict[str, Any]]


@router.get("/my", response_model=FeaturesMyResponse)
@limiter.limit("60/minute")
def get_my_feature_instances(
    request: Request,
    context: RequestContext = Depends(getRequestContext)
) -> FeaturesMyResponse:
    """
    Get all feature instances the current user has access to.
    
    Returns hierarchical structure: mandates -> features -> instances -> permissions
    This endpoint does not require X-Mandate-Id header.
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Get all feature accesses for this user
        featureAccesses = rootInterface.getFeatureAccessesForUser(str(context.user.id))
        
        if not featureAccesses:
            return FeaturesMyResponse(mandates=[])
        
        # Build hierarchical structure: mandate -> feature -> instances
        mandatesMap: Dict[str, Dict[str, Any]] = {}
        featuresMap: Dict[str, Dict[str, Any]] = {}  # key: mandateId_featureCode
        
        for access in featureAccesses:
            if not access.enabled:
                continue
            
            instance = featureInterface.getFeatureInstance(str(access.featureInstanceId))
            if not instance or not instance.enabled:
                continue
            
            # Get mandate info
            mandateId = str(instance.mandateId)
            if mandateId not in mandatesMap:
                mandate = rootInterface.getMandate(mandateId)
                if mandate:
                    mandatesMap[mandateId] = {
                        "id": mandateId,
                        "name": mandate.name if hasattr(mandate, 'name') else mandateId,
                        "code": mandate.code if hasattr(mandate, 'code') else None,
                        "features": []
                    }
                else:
                    mandatesMap[mandateId] = {
                        "id": mandateId,
                        "name": mandateId,
                        "code": None,
                        "features": []
                    }
            
            # Get feature info from catalog (features are code-defined)
            featureKey = f"{mandateId}_{instance.featureCode}"
            if featureKey not in featuresMap:
                catalogService = getCatalogService()
                featureDef = catalogService.getFeatureDefinition(instance.featureCode)
                featuresMap[featureKey] = {
                    "code": instance.featureCode,
                    "label": featureDef.get("label", {"de": instance.featureCode, "en": instance.featureCode}) if featureDef else {"de": instance.featureCode, "en": instance.featureCode},
                    "icon": featureDef.get("icon", "folder") if featureDef else "folder",
                    "instances": [],
                    "_mandateId": mandateId  # Temporary for grouping
                }
            
            # Get user's roles in this instance (can have multiple)
            userRoles = _getUserRolesInInstance(rootInterface, str(context.user.id), str(instance.id))
            
            # Get permissions for this instance
            permissions = _getInstancePermissions(rootInterface, str(context.user.id), str(instance.id))
            
            # Add instance to feature
            featuresMap[featureKey]["instances"].append({
                "id": str(instance.id),
                "featureCode": instance.featureCode,
                "mandateId": mandateId,
                "mandateName": mandatesMap[mandateId]["name"],
                "instanceLabel": instance.label,
                "userRoles": userRoles,
                "permissions": permissions
            })
        
        # Build final structure
        for featureKey, featureData in featuresMap.items():
            mandateId = featureData.pop("_mandateId")
            mandatesMap[mandateId]["features"].append(featureData)
        
        return FeaturesMyResponse(mandates=list(mandatesMap.values()))
        
    except Exception as e:
        logger.error(f"Error getting user's feature instances: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to get feature instances: {str(e)}"
        )


def _getUserRolesInInstance(rootInterface, userId: str, instanceId: str) -> List[str]:
    """Get all role labels for a user in a feature instance."""
    try:
        # Get FeatureAccess for this user and instance (Pydantic model)
        featureAccess = rootInterface.getFeatureAccess(userId, instanceId)
        
        if featureAccess:
            # Get role IDs via interface method
            roleIds = rootInterface.getRoleIdsForFeatureAccess(str(featureAccess.id))
            
            if roleIds:
                # Get ALL roles and extract labels
                roleLabels = []
                for roleId in roleIds:
                    role = rootInterface.getRole(roleId)
                    if role:
                        roleLabels.append(role.roleLabel)
                return roleLabels if roleLabels else ["user"]
        
        return ["user"]  # Default - no access means basic user level
    except Exception as e:
        logger.debug(f"Error getting user roles: {e}")
        return ["user"]  # Fail-safe: default to basic user


def _getInstancePermissions(rootInterface, userId: str, instanceId: str) -> Dict[str, Any]:
    """Get summarized permissions for a user in an instance."""
    # Default permissions structure
    permissions = {
        "tables": {},
        "views": {},
        "fields": {},
        "isAdmin": False  # Flag if user has admin role
    }
    
    try:
        from modules.datamodels.datamodelRbac import AccessRuleContext
        
        # Get FeatureAccess for this user and instance (Pydantic model)
        featureAccess = rootInterface.getFeatureAccess(userId, instanceId)
        
        logger.debug(f"_getInstancePermissions: userId={userId}, instanceId={instanceId}, featureAccess={featureAccess is not None}")
        
        if not featureAccess:
            logger.debug(f"_getInstancePermissions: No FeatureAccess found for user {userId} and instance {instanceId}")
            return permissions
        
        # Get role IDs via interface method
        roleIds = rootInterface.getRoleIdsForFeatureAccess(str(featureAccess.id))
        
        logger.debug(f"_getInstancePermissions: featureAccessId={featureAccess.id}, roleIds={roleIds}")
        
        if not roleIds:
            logger.debug(f"_getInstancePermissions: No roles found for FeatureAccess {featureAccess.id}")
            return permissions
        
        # Check if user has admin role
        for roleId in roleIds:
            role = rootInterface.getRole(roleId)
            if role and "admin" in role.roleLabel.lower():
                permissions["isAdmin"] = True
                break
        
        # Get permissions (AccessRules) for all roles
        for roleId in roleIds:
            # Get all rules for this role (returns Pydantic models)
            accessRules = rootInterface.getAccessRules(roleId=roleId)
            
            logger.debug(f"_getInstancePermissions: roleId={roleId}, accessRules={len(accessRules) if accessRules else 0}")
            
            for rule in accessRules:
                context = rule.context
                item = rule.item or ""
                
                # Handle DATA context (tables/fields)
                if context == AccessRuleContext.DATA or context == "DATA":
                    if item:
                        # Check if it's a field (table.field) or table
                        if "." in item:
                            tableName, fieldName = item.split(".", 1)
                            if fieldName not in permissions["fields"]:
                                permissions["fields"][fieldName] = {"view": False}
                            permissions["fields"][fieldName]["view"] = permissions["fields"][fieldName]["view"] or rule.view
                        else:
                            tableName = item
                            if tableName not in permissions["tables"]:
                                permissions["tables"][tableName] = {
                                    "view": False,
                                    "read": "n",
                                    "create": "n",
                                    "update": "n",
                                    "delete": "n"
                                }
                            
                            # Merge permissions (highest wins)
                            current = permissions["tables"][tableName]
                            current["view"] = current["view"] or rule.view
                            current["read"] = _mergeAccessLevel(current["read"], rule.read or "n")
                            current["create"] = _mergeAccessLevel(current["create"], rule.create or "n")
                            current["update"] = _mergeAccessLevel(current["update"], rule.update or "n")
                            current["delete"] = _mergeAccessLevel(current["delete"], rule.delete or "n")
                
                # Handle UI context (views)
                elif context == AccessRuleContext.UI or context == "UI":
                    if item:
                        # Store with full objectKey as per Navigation-API-Konzept
                        permissions["views"][item] = permissions["views"].get(item, False) or rule.view
                    elif rule.view:
                        # item=None means all views - set a wildcard flag
                        permissions["views"]["_all"] = True
        
        return permissions
        
    except Exception as e:
        logger.debug(f"Error getting instance permissions: {e}")
        return permissions  # Fail-safe: no permissions on error


def _mergeAccessLevel(current: str, new: str) -> str:
    """Merge two access levels, returning the highest."""
    levels = {"n": 0, "m": 1, "g": 2, "a": 3}
    currentLevel = levels.get(current, 0)
    newLevel = levels.get(new, 0)
    
    if newLevel > currentLevel:
        return new
    return current


@router.post("/", response_model=Dict[str, Any])
@limiter.limit("10/minute")
def create_feature(
    request: Request,
    code: str = Query(..., description="Unique feature code"),
    label: Dict[str, str] = None,
    icon: str = Query("mdi-puzzle", description="Icon identifier"),
    sysAdmin: User = Depends(requireSysAdminRole)
) -> Dict[str, Any]:
    """
    Create a new feature definition.
    
    SysAdmin only - creates a global feature that can be activated for mandates.
    
    Args:
        code: Unique feature code (e.g., 'trustee')
        label: I18n labels (e.g., {"en": "Trustee", "de": "Treuhand"})
        icon: Icon identifier
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Check if feature already exists in catalog (features are code-defined)
        catalogService = getCatalogService()
        existing = catalogService.getFeatureDefinition(code)
        if existing:
            raise HTTPException(
                status_code=status.HTTP_409_CONFLICT,
                detail=f"Feature '{code}' already exists"
            )
        
        feature = featureInterface.createFeature(
            code=code,
            label=label or {"en": code.title(), "de": code.title()},
            icon=icon
        )
        
        logger.info(f"SysAdmin {sysAdmin.id} created feature '{code}'")
        return feature.model_dump()
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error creating feature: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to create feature: {str(e)}"
        )


# =============================================================================
# Feature Instance Endpoints (Mandate-scoped)
# =============================================================================

@router.get("/instances", response_model=List[Dict[str, Any]])
@limiter.limit("60/minute")
def list_feature_instances(
    request: Request,
    featureCode: Optional[str] = Query(None, description="Filter by feature code"),
    context: RequestContext = Depends(getRequestContext)
) -> List[Dict[str, Any]]:
    """
    List feature instances for the current mandate.
    
    Returns instances the user has access to within the selected mandate.
    
    Args:
        featureCode: Optional filter by feature code
    """
    if not context.mandateId:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="X-Mandate-Id header is required"
        )
    
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        instances = featureInterface.getFeatureInstancesForMandate(
            mandateId=str(context.mandateId),
            featureCode=featureCode
        )
        
        return [inst.model_dump() for inst in instances]
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error listing feature instances: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to list feature instances: {str(e)}"
        )


@router.get("/instances/{instanceId}", response_model=Dict[str, Any])
@limiter.limit("60/minute")
def get_feature_instance(
    request: Request,
    instanceId: str,
    context: RequestContext = Depends(getRequestContext)
) -> Dict[str, Any]:
    """
    Get a specific feature instance.
    
    Args:
        instanceId: FeatureInstance ID
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        instance = featureInterface.getFeatureInstance(instanceId)
        if not instance:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature instance '{instanceId}' not found"
            )
        
        # Verify mandate access (unless SysAdmin)
        if context.mandateId and str(instance.mandateId) != str(context.mandateId):
            if not context.hasSysAdminRole:
                raise HTTPException(
                    status_code=status.HTTP_403_FORBIDDEN,
                    detail="Access denied to this feature instance"
                )
        
        return instance.model_dump()
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error getting feature instance {instanceId}: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to get feature instance: {str(e)}"
        )


@router.post("/instances", response_model=Dict[str, Any])
@limiter.limit("10/minute")
def create_feature_instance(
    request: Request,
    data: FeatureInstanceCreate,
    context: RequestContext = Depends(getRequestContext)
) -> Dict[str, Any]:
    """
    Create a new feature instance for the current mandate.
    
    Requires Mandate-Admin role. Template roles are optionally copied.
    
    Args:
        data: Feature instance creation data
    """
    if not context.mandateId:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="X-Mandate-Id header is required"
        )
    
    # Check mandate admin permission
    if not _hasMandateAdminRole(context):
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Mandate-Admin role required to create feature instances"
        )
    
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Verify feature exists in catalog (features are code-defined, not DB-stored)
        catalogService = getCatalogService()
        featureDef = catalogService.getFeatureDefinition(data.featureCode)
        if not featureDef:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature '{data.featureCode}' not found"
            )
        
        instance = featureInterface.createFeatureInstance(
            featureCode=data.featureCode,
            mandateId=str(context.mandateId),
            label=data.label,
            enabled=data.enabled,
            copyTemplateRoles=data.copyTemplateRoles,
            config=data.config
        )
        
        logger.info(
            f"User {context.user.id} created feature instance '{data.label}' "
            f"for feature '{data.featureCode}' in mandate {context.mandateId}"
        )
        
        return instance.model_dump()
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error creating feature instance: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to create feature instance: {str(e)}"
        )


@router.delete("/instances/{instanceId}", response_model=Dict[str, str])
@limiter.limit("10/minute")
def delete_feature_instance(
    request: Request,
    instanceId: str,
    context: RequestContext = Depends(getRequestContext)
) -> Dict[str, str]:
    """
    Delete a feature instance.
    
    Requires Mandate-Admin role. CASCADE will delete associated roles and access records.
    
    Args:
        instanceId: FeatureInstance ID
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Get instance to verify access
        instance = featureInterface.getFeatureInstance(instanceId)
        if not instance:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature instance '{instanceId}' not found"
            )
        
        # Verify mandate access
        if context.mandateId and str(instance.mandateId) != str(context.mandateId):
            if not context.hasSysAdminRole:
                raise HTTPException(
                    status_code=status.HTTP_403_FORBIDDEN,
                    detail="Access denied to this feature instance"
                )
        
        # Check mandate admin permission
        if not _hasMandateAdminRole(context) and not context.hasSysAdminRole:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Mandate-Admin role required to delete feature instances"
            )
        
        featureInterface.deleteFeatureInstance(instanceId)
        
        logger.info(f"User {context.user.id} deleted feature instance {instanceId}")
        
        return {"message": "Feature instance deleted", "instanceId": instanceId}
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error deleting feature instance {instanceId}: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to delete feature instance: {str(e)}"
        )


class FeatureInstanceUpdate(BaseModel):
    """Request model for updating a feature instance."""
    label: Optional[str] = Field(None, description="New label for the instance")
    enabled: Optional[bool] = Field(None, description="Enable/disable the instance")
    config: Optional[Dict[str, Any]] = Field(None, description="Instance-specific configuration (JSONB). Structure depends on featureCode.")


@router.put("/instances/{instanceId}", response_model=Dict[str, Any])
@limiter.limit("30/minute")
def updateFeatureInstance(
    request: Request,
    instanceId: str,
    data: FeatureInstanceUpdate,
    context: RequestContext = Depends(getRequestContext)
) -> Dict[str, Any]:
    """
    Update a feature instance (label, enabled).
    
    Requires Mandate-Admin role.
    
    Args:
        instanceId: FeatureInstance ID
        data: Fields to update (label, enabled)
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Verify instance exists
        instance = featureInterface.getFeatureInstance(instanceId)
        if not instance:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature instance '{instanceId}' not found"
            )
        
        # Verify mandate access
        if context.mandateId and str(instance.mandateId) != str(context.mandateId):
            if not context.hasSysAdminRole:
                raise HTTPException(
                    status_code=status.HTTP_403_FORBIDDEN,
                    detail="Access denied to this feature instance"
                )
        
        # Check mandate admin permission
        if not _hasMandateAdminRole(context) and not context.hasSysAdminRole:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Mandate-Admin role required to update feature instances"
            )
        
        # Build update data (only non-None values)
        updateData = {}
        if data.label is not None:
            updateData["label"] = data.label
        if data.enabled is not None:
            updateData["enabled"] = data.enabled
        if data.config is not None:
            updateData["config"] = data.config
        
        if not updateData:
            return instance.model_dump()
        
        updated = featureInterface.updateFeatureInstance(instanceId, updateData)
        if not updated:
            raise HTTPException(
                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                detail="Failed to update feature instance"
            )
        
        logger.info(f"User {context.user.id} updated feature instance {instanceId}: {updateData}")
        
        return updated.model_dump()
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error updating feature instance {instanceId}: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to update feature instance: {str(e)}"
        )


@router.post("/instances/{instanceId}/sync-roles", response_model=SyncRolesResult)
@limiter.limit("10/minute")
def sync_instance_roles(
    request: Request,
    instanceId: str,
    addOnly: bool = Query(True, description="Only add missing roles, don't remove extras"),
    context: RequestContext = Depends(getRequestContext)
) -> SyncRolesResult:
    """
    Synchronize roles of a feature instance with current templates.
    
    IMPORTANT: Templates are only copied when a FeatureInstance is created.
    This sync function is for manual re-synchronization, not automatic propagation.
    
    Args:
        instanceId: FeatureInstance ID
        addOnly: If True, only add missing roles. If False, also remove extras.
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Get instance to verify access
        instance = featureInterface.getFeatureInstance(instanceId)
        if not instance:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature instance '{instanceId}' not found"
            )
        
        # Verify mandate access
        if context.mandateId and str(instance.mandateId) != str(context.mandateId):
            if not context.hasSysAdminRole:
                raise HTTPException(
                    status_code=status.HTTP_403_FORBIDDEN,
                    detail="Access denied to this feature instance"
                )
        
        # Check admin permission (Mandate-Admin or Feature-Admin)
        if not _hasMandateAdminRole(context) and not context.hasSysAdminRole:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Admin role required to sync roles"
            )
        
        result = featureInterface.syncRolesFromTemplate(instanceId, addOnly)
        
        logger.info(
            f"User {context.user.id} synced roles for instance {instanceId}: {result}"
        )
        
        return SyncRolesResult(**result)
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error syncing roles for instance {instanceId}: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to sync roles: {str(e)}"
        )


# =============================================================================
# Template Role Endpoints (SysAdmin only)
# =============================================================================

@router.get("/templates/roles", response_model=List[Dict[str, Any]])
@limiter.limit("60/minute")
def list_template_roles(
    request: Request,
    featureCode: Optional[str] = Query(None, description="Filter by feature code"),
    sysAdmin: User = Depends(requireSysAdminRole)
) -> List[Dict[str, Any]]:
    """
    List global template roles.
    
    SysAdmin only - returns template roles that are copied to new feature instances.
    
    Args:
        featureCode: Optional filter by feature code
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        roles = featureInterface.getTemplateRoles(featureCode)
        return [r.model_dump() for r in roles]
        
    except Exception as e:
        logger.error(f"Error listing template roles: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to list template roles: {str(e)}"
        )


@router.post("/templates/roles", response_model=Dict[str, Any])
@limiter.limit("10/minute")
def create_template_role(
    request: Request,
    roleLabel: str = Query(..., description="Role label (e.g., 'admin', 'viewer')"),
    featureCode: str = Query(..., description="Feature code this role belongs to"),
    description: Dict[str, str] = None,
    sysAdmin: User = Depends(requireSysAdminRole)
) -> Dict[str, Any]:
    """
    Create a global template role for a feature.
    
    SysAdmin only - new template roles are NOT automatically propagated to existing instances.
    Use the sync-roles endpoint to manually synchronize.
    
    Args:
        roleLabel: Role label
        featureCode: Feature code
        description: I18n descriptions
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Verify feature exists in catalog (features are code-defined)
        catalogService = getCatalogService()
        featureDef = catalogService.getFeatureDefinition(featureCode)
        if not featureDef:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature '{featureCode}' not found"
            )
        
        role = featureInterface.createTemplateRole(
            roleLabel=roleLabel,
            featureCode=featureCode,
            description=description
        )
        
        logger.info(
            f"SysAdmin {sysAdmin.id} created template role '{roleLabel}' "
            f"for feature '{featureCode}'"
        )
        
        return role.model_dump()
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error creating template role: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to create template role: {str(e)}"
        )


# =============================================================================
# Feature Instance Users Endpoints
# Manage which users have access to a specific feature instance
# =============================================================================

class FeatureInstanceUserCreate(BaseModel):
    """Request model for adding a user to a feature instance"""
    userId: str = Field(..., description="User ID to add")
    roleIds: List[str] = Field(default_factory=list, description="Role IDs to assign")


class FeatureInstanceUserResponse(BaseModel):
    """Response model for a user in a feature instance"""
    id: str  # Use the FeatureAccess ID as primary key
    userId: str
    username: str
    email: Optional[str]
    fullName: Optional[str]
    roleIds: List[str]
    roleLabels: List[str]
    enabled: bool


class FeatureInstanceUserUpdate(BaseModel):
    """Request model for updating a feature instance user (roles and active flag)"""
    roleIds: List[str] = Field(..., description="Role IDs to assign")
    enabled: Optional[bool] = Field(None, description="Whether this user's access is active (omit to leave unchanged)")


@router.get("/instances/{instanceId}/users", response_model=List[FeatureInstanceUserResponse])
@limiter.limit("60/minute")
def list_feature_instance_users(
    request: Request,
    instanceId: str,
    context: RequestContext = Depends(getRequestContext)
) -> List[FeatureInstanceUserResponse]:
    """
    List all users with access to a specific feature instance.
    
    Returns users and their roles for the given instance.
    
    Args:
        instanceId: FeatureInstance ID
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Verify instance exists
        instance = featureInterface.getFeatureInstance(instanceId)
        if not instance:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature instance '{instanceId}' not found"
            )
        
        # Verify mandate access (unless SysAdmin)
        if context.mandateId and str(instance.mandateId) != str(context.mandateId):
            if not context.hasSysAdminRole:
                raise HTTPException(
                    status_code=status.HTTP_403_FORBIDDEN,
                    detail="Access denied to this feature instance"
                )
        
        # Get all FeatureAccess records for this instance (Pydantic models)
        featureAccesses = rootInterface.getFeatureAccessesByInstance(instanceId)
        
        result = []
        for fa in featureAccesses:
            # Get user info (Pydantic model)
            user = rootInterface.getUser(str(fa.userId))
            if not user:
                continue
            
            # Get role IDs via interface method
            roleIds = rootInterface.getRoleIdsForFeatureAccess(str(fa.id))
            
            # Get role labels
            roleLabels = []
            for roleId in roleIds:
                role = rootInterface.getRole(roleId)
                if role:
                    roleLabels.append(role.roleLabel)
            
            result.append(FeatureInstanceUserResponse(
                id=str(fa.id),  # FeatureAccess ID as primary key
                userId=str(fa.userId),
                username=user.username,
                email=user.email,
                fullName=user.fullName,
                roleIds=roleIds,
                roleLabels=roleLabels,
                enabled=fa.enabled
            ))
        
        return result
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error listing feature instance users: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to list feature instance users: {str(e)}"
        )


@router.post("/instances/{instanceId}/users", response_model=Dict[str, Any])
@limiter.limit("30/minute")
def add_user_to_feature_instance(
    request: Request,
    instanceId: str,
    data: FeatureInstanceUserCreate,
    context: RequestContext = Depends(getRequestContext)
) -> Dict[str, Any]:
    """
    Add a user to a feature instance with specified roles.
    
    Creates a FeatureAccess record and associated FeatureAccessRole records.
    
    Args:
        instanceId: FeatureInstance ID
        data: User and role data
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Verify instance exists
        instance = featureInterface.getFeatureInstance(instanceId)
        if not instance:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature instance '{instanceId}' not found"
            )
        
        # Verify mandate access
        if context.mandateId and str(instance.mandateId) != str(context.mandateId):
            if not context.hasSysAdminRole:
                raise HTTPException(
                    status_code=status.HTTP_403_FORBIDDEN,
                    detail="Access denied to this feature instance"
                )
        
        # Check admin permission
        if not _hasMandateAdminRole(context) and not context.hasSysAdminRole:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Admin role required to add users to feature instances"
            )
        
        # Verify user exists
        user = rootInterface.getUser(data.userId)
        if not user:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"User '{data.userId}' not found"
            )
        
        # Check if user already has access
        from modules.datamodels.datamodelMembership import FeatureAccess, FeatureAccessRole
        existingAccess = rootInterface.getFeatureAccess(data.userId, instanceId)
        if existingAccess:
            raise HTTPException(
                status_code=status.HTTP_409_CONFLICT,
                detail="User already has access to this feature instance"
            )
        
        # Create FeatureAccess record
        featureAccess = FeatureAccess(
            userId=data.userId,
            featureInstanceId=instanceId,
            enabled=True
        )
        createdAccess = rootInterface.db.recordCreate(FeatureAccess, featureAccess.model_dump())
        featureAccessId = createdAccess.get("id")
        
        # Create FeatureAccessRole records for each role
        for roleId in data.roleIds:
            featureAccessRole = FeatureAccessRole(
                featureAccessId=featureAccessId,
                roleId=roleId
            )
            rootInterface.db.recordCreate(FeatureAccessRole, featureAccessRole.model_dump())
        
        logger.info(
            f"User {context.user.id} added user {data.userId} to feature instance {instanceId} "
            f"with roles {data.roleIds}"
        )
        
        return {
            "featureAccessId": featureAccessId,
            "userId": data.userId,
            "featureInstanceId": instanceId,
            "roleIds": data.roleIds,
            "enabled": True
        }
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error adding user to feature instance: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to add user to feature instance: {str(e)}"
        )


@router.delete("/instances/{instanceId}/users/{userId}", response_model=Dict[str, str])
@limiter.limit("30/minute")
def remove_user_from_feature_instance(
    request: Request,
    instanceId: str,
    userId: str,
    context: RequestContext = Depends(getRequestContext)
) -> Dict[str, str]:
    """
    Remove a user's access from a feature instance.
    
    Deletes the FeatureAccess record (CASCADE will delete FeatureAccessRole records).
    
    Args:
        instanceId: FeatureInstance ID
        userId: User ID to remove
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Verify instance exists
        instance = featureInterface.getFeatureInstance(instanceId)
        if not instance:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature instance '{instanceId}' not found"
            )
        
        # Verify mandate access
        if context.mandateId and str(instance.mandateId) != str(context.mandateId):
            if not context.hasSysAdminRole:
                raise HTTPException(
                    status_code=status.HTTP_403_FORBIDDEN,
                    detail="Access denied to this feature instance"
                )
        
        # Check admin permission
        if not _hasMandateAdminRole(context) and not context.hasSysAdminRole:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Admin role required to remove users from feature instances"
            )
        
        # Find FeatureAccess record
        from modules.datamodels.datamodelMembership import FeatureAccess
        existingAccess = rootInterface.getFeatureAccess(userId, instanceId)
        if not existingAccess:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail="User does not have access to this feature instance"
            )
        
        featureAccessId = str(existingAccess.id)
        
        # Delete FeatureAccess (CASCADE will delete FeatureAccessRole records)
        rootInterface.db.recordDelete(FeatureAccess, featureAccessId)
        
        logger.info(
            f"User {context.user.id} removed user {userId} from feature instance {instanceId}"
        )
        
        return {
            "message": "User access removed",
            "userId": userId,
            "featureInstanceId": instanceId
        }
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error removing user from feature instance: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to remove user from feature instance: {str(e)}"
        )


@router.put("/instances/{instanceId}/users/{userId}/roles", response_model=Dict[str, Any])
@limiter.limit("30/minute")
def update_feature_instance_user_roles(
    request: Request,
    instanceId: str,
    userId: str,
    data: FeatureInstanceUserUpdate,
    context: RequestContext = Depends(getRequestContext)
) -> Dict[str, Any]:
    """
    Update a user's roles and active flag in a feature instance.
    
    Replaces all existing FeatureAccessRole records with new ones.
    If enabled is provided, updates the FeatureAccess.enabled flag.
    
    Args:
        instanceId: FeatureInstance ID
        userId: User ID to update
        data: roleIds and optional enabled
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Verify instance exists
        instance = featureInterface.getFeatureInstance(instanceId)
        if not instance:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature instance '{instanceId}' not found"
            )
        
        # Verify mandate access
        if context.mandateId and str(instance.mandateId) != str(context.mandateId):
            if not context.hasSysAdminRole:
                raise HTTPException(
                    status_code=status.HTTP_403_FORBIDDEN,
                    detail="Access denied to this feature instance"
                )
        
        # Check admin permission
        if not _hasMandateAdminRole(context) and not context.hasSysAdminRole:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Admin role required to update user roles"
            )
        
        # Find FeatureAccess record
        from modules.datamodels.datamodelMembership import FeatureAccess, FeatureAccessRole
        existingAccess = rootInterface.getFeatureAccess(userId, instanceId)
        if not existingAccess:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail="User does not have access to this feature instance"
            )
        
        featureAccessId = str(existingAccess.id)
        
        # Update enabled flag if provided
        if data.enabled is not None:
            rootInterface.db.recordModify(FeatureAccess, featureAccessId, {"enabled": data.enabled})
        
        # Delete existing FeatureAccessRole records via interface method
        rootInterface.deleteFeatureAccessRoles(featureAccessId)
        
        # Create new FeatureAccessRole records
        for roleId in data.roleIds:
            featureAccessRole = FeatureAccessRole(
                featureAccessId=featureAccessId,
                roleId=roleId
            )
            rootInterface.db.recordCreate(FeatureAccessRole, featureAccessRole.model_dump())
        
        logger.info(
            f"User {context.user.id} updated roles for user {userId} in feature instance {instanceId}: {data.roleIds}"
        )
        
        return {
            "featureAccessId": featureAccessId,
            "userId": userId,
            "featureInstanceId": instanceId,
            "roleIds": data.roleIds,
            "enabled": data.enabled if data.enabled is not None else existingAccess[0].get("enabled", True)
        }
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error updating user roles in feature instance: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to update user roles: {str(e)}"
        )


@router.get("/instances/{instanceId}/available-roles", response_model=List[Dict[str, Any]])
@limiter.limit("60/minute")
def get_feature_instance_available_roles(
    request: Request,
    instanceId: str,
    context: RequestContext = Depends(getRequestContext)
) -> List[Dict[str, Any]]:
    """
    Get available roles for a feature instance.
    
    Returns instance-specific roles (copied from templates) that can be assigned to users.
    
    Args:
        instanceId: FeatureInstance ID
    """
    try:
        rootInterface = getRootInterface()
        featureInterface = getFeatureInterface(rootInterface.db)
        
        # Verify instance exists
        instance = featureInterface.getFeatureInstance(instanceId)
        if not instance:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature instance '{instanceId}' not found"
            )
        
        # Verify mandate access
        if context.mandateId and str(instance.mandateId) != str(context.mandateId):
            if not context.hasSysAdminRole:
                raise HTTPException(
                    status_code=status.HTTP_403_FORBIDDEN,
                    detail="Access denied to this feature instance"
                )
        
        # Get roles for this instance using interface method
        instanceRoles = rootInterface.getRolesByFeatureInstance(instanceId)
        
        result = []
        for role in instanceRoles:
            result.append({
                "id": role.id,
                "roleLabel": role.roleLabel,
                "description": role.description or {},
                "featureCode": role.featureCode,
                "isSystemRole": role.isSystemRole
            })
        
        return result
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error getting available roles for feature instance: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to get available roles: {str(e)}"
        )


# =============================================================================
# Dynamic Feature Route (MUST be last to avoid catching /instances, /my, etc.)
# =============================================================================

@router.get("/{featureCode}", response_model=Dict[str, Any])
@limiter.limit("60/minute")
def get_feature(
    request: Request,
    featureCode: str,
    context: RequestContext = Depends(getRequestContext)
) -> Dict[str, Any]:
    """
    Get a specific feature by code.
    
    IMPORTANT: This route must be defined LAST to avoid catching paths like
    /instances, /my, /templates, etc.
    
    Args:
        featureCode: Feature code (e.g., 'trustee', 'chatbot')
    """
    try:
        # Features come from the RBAC Catalog (code-defined, not DB-stored)
        catalogService = getCatalogService()
        featureDef = catalogService.getFeatureDefinition(featureCode)
        if not featureDef:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"Feature '{featureCode}' not found"
            )
        
        return featureDef
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error getting feature {featureCode}: {e}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to get feature: {str(e)}"
        )


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

def _hasMandateAdminRole(context: RequestContext) -> bool:
    """
    Check if the user has mandate admin role in the current context.
    
    A user is mandate admin if they have the 'admin' role at mandate level.
    """
    if context.hasSysAdminRole:
        return True
    
    if not context.roleIds:
        return False
    
    # Check if any of the user's roles is an admin role
    try:
        rootInterface = getRootInterface()
        
        for roleId in context.roleIds:
            role = rootInterface.getRole(roleId)
            if role:
                roleLabel = role.roleLabel
                # Admin role at mandate level (not feature-instance level)
                if roleLabel == "admin" and not role.featureInstanceId:
                    return True
        
        return False
        
    except Exception as e:
        logger.error(f"Error checking mandate admin role: {e}")
        return False
