api/admin_routes.py

"""
Admin User Management API Routes
Handles administrative users and role-based access control
"""
from datetime import datetime
import logging
from typing import Dict, List, Optional
from fastapi import Depends, Request, status
from pydantic import BaseModel, ConfigDict, EmailStr, Field
from sqlalchemy.orm import Session

from core.api_governance import ActionComplexity, require_governance
from core.auth import get_current_user
from core.base_routes import BaseAPIRouter
from core.database import get_db
from core.exceptions import (
    MissingFieldError,
    UserAlreadyExistsError,
    UserNotFoundError,
    ValidationError,
    WorkspaceNotFoundError,
)
from core.models import AdminRole, AdminUser, User

router = BaseAPIRouter(prefix="/api/admin", tags=["Admin"])
logger = logging.getLogger(__name__)


async def require_super_admin(current_user: User = Depends(get_current_user)) -> User:
    """
    Dependency that requires super_admin role

    Raises 403 if current user is not a super_admin
    """
    if current_user.role != "super_admin":
        raise router.permission_denied_error(
            action="access_admin_endpoints",
            resource="Admin",
            details={"required_role": "super_admin", "actual_role": current_user.role}
        )
    return current_user


# Request/Response Models
class AdminUserWithRole(BaseModel):
    """Admin user with role information"""
    id: str
    email: str
    name: str
    role_id: str
    role_name: str
    permissions: dict
    status: str
    last_login: Optional[datetime]

    model_config = ConfigDict(from_attributes=True)


class UpdateLastLoginResponse(BaseModel):
    """Response after updating last login"""
    message: str


class CreateAdminUserRequest(BaseModel):
    """Request to create a new admin user"""
    email: EmailStr
    name: str = Field(..., min_length=1, max_length=255)
    password: str = Field(..., min_length=8)
    role_id: str = Field(..., description="ID of the admin role to assign")


class UpdateAdminUserRequest(BaseModel):
    """Request to update an admin user"""
    name: Optional[str] = Field(None, min_length=1, max_length=255)
    role_id: Optional[str] = Field(None, description="ID of the admin role to assign")
    status: Optional[str] = Field(None, description="Admin status (active, inactive)")


class AdminUserResponse(BaseModel):
    """Detailed admin user response"""
    id: str
    email: str
    name: str
    role_id: str
    status: str
    last_login: Optional[datetime]
    created_at: Optional[datetime]

    model_config = ConfigDict(from_attributes=True)


class DeleteAdminUserResponse(BaseModel):
    """Response after deleting admin user"""
    message: str


class CreateAdminRoleRequest(BaseModel):
    """Request to create a new admin role"""
    name: str = Field(..., min_length=1, max_length=100, unique=True, description="Role name (must be unique)")
    permissions: Dict[str, bool] = Field(..., description="Permissions dict (e.g., {'users': true, 'workflows': false})")
    description: Optional[str] = Field(None, max_length=500, description="Role description")


class UpdateAdminRoleRequest(BaseModel):
    """Request to update an admin role"""
    name: Optional[str] = Field(None, min_length=1, max_length=100)
    permissions: Optional[Dict[str, bool]] = Field(None, description="Permissions dict")
    description: Optional[str] = Field(None, max_length=500, description="Role description")


class AdminRoleResponse(BaseModel):
    """Admin role response"""
    id: str
    name: str
    permissions: Dict[str, bool]
    description: Optional[str]

    model_config = ConfigDict(from_attributes=True)


class DeleteAdminRoleResponse(BaseModel):
    """Response after deleting admin role"""
    message: str


# Endpoints
@router.get("/users", response_model=List[AdminUserWithRole])
async def list_admin_users(
    current_admin: User = Depends(require_super_admin),
    db: Session = Depends(get_db)
):
    """
    List all admin users with their roles

    Requires super_admin role.
    Returns comprehensive list of admin users including permissions.
    """
    # Query admin users with roles
    admin_users = db.query(AdminUser).join(AdminRole).all()

    return [
        AdminUserWithRole(
            id=admin.id,
            email=admin.email,
            name=admin.name,
            role_id=admin.role_id,
            role_name=admin.role.name,
            permissions=admin.role.permissions or {},
            status=admin.status,
            last_login=admin.last_login
        )
        for admin in admin_users
    ]


@router.get("/users/{admin_id}", response_model=AdminUserResponse)
async def get_admin_user(
    admin_id: str,
    current_admin: User = Depends(require_super_admin),
    db: Session = Depends(get_db)
):
    """
    Get specific admin user by ID

    Returns detailed admin user information.
    """
    admin = db.query(AdminUser).filter(AdminUser.id == admin_id).first()

    if not admin:
        raise router.not_found_error("AdminUser", admin_id)

    return AdminUserResponse(
        id=admin.id,
        email=admin.email,
        name=admin.name,
        role_id=admin.role_id,
        status=admin.status,
        last_login=admin.last_login,
        created_at=admin.created_at
    )


@router.post("/users", response_model=AdminUserResponse, status_code=status.HTTP_201_CREATED)
@require_governance(
    action_complexity=ActionComplexity.CRITICAL,
    action_name="create_admin_user",
    feature="admin"
)
async def create_admin_user(
    request: CreateAdminUserRequest,
    http_request: Request,
    current_admin: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Create a new admin user

    Creates a new admin user with the specified role.
    Requires super_admin role.

    **Governance**: Agent-based creation requires AUTONOMOUS maturity (CRITICAL).
    - Admin user creation is a critical action
    - Requires AUTONOMOUS maturity for agents
    """
    # Check if role exists
    role = db.query(AdminRole).filter(AdminRole.id == request.role_id).first()
    if not role:
        raise router.not_found_error(
            "AdminRole",
            request.role_id,
            details={"field": "role_id"}
        )

    # Check if email already exists
    existing = db.query(AdminUser).filter(AdminUser.email == request.email).first()
    if existing:
        raise router.conflict_error(
            message="Admin user with this email already exists",
            conflicting_resource=request.email,
            details={"field": "email", "email": request.email}
        )

    # Hash password (import from auth)
    from core.auth import get_password_hash
    password_hash = get_password_hash(request.password)

    admin = AdminUser(
        email=request.email,
        name=request.name,
        password_hash=password_hash,
        role_id=request.role_id,
        status="active"
    )

    db.add(admin)
    db.commit()
    db.refresh(admin)

    logger.info(f"Admin user created: {admin.id} by {current_admin.id}")
    return AdminUserResponse(
        id=admin.id,
        email=admin.email,
        name=admin.name,
        role_id=admin.role_id,
        status=admin.status,
        last_login=admin.last_login,
        created_at=admin.created_at
    )


@router.patch("/users/{admin_id}", response_model=AdminUserResponse)
async def update_admin_user(
    admin_id: str,
    request: UpdateAdminUserRequest,
    current_admin: User = Depends(require_super_admin),
    db: Session = Depends(get_db)
):
    """
    Update admin user

    Updates admin user information. Only provided fields are updated.
    Requires super_admin role.
    """
    admin = db.query(AdminUser).filter(AdminUser.id == admin_id).first()

    if not admin:
        raise router.not_found_error("AdminUser", admin_id)

    # Update only provided fields
    if request.name is not None:
        admin.name = request.name
    if request.role_id is not None:
        # Verify role exists
        role = db.query(AdminRole).filter(AdminRole.id == request.role_id).first()
        if not role:
            raise router.not_found_error(
                "AdminRole",
                request.role_id,
                details={"field": "role_id"}
            )
        admin.role_id = request.role_id
    if request.status is not None:
        admin.status = request.status

    db.commit()
    db.refresh(admin)

    return AdminUserResponse(
        id=admin.id,
        email=admin.email,
        name=admin.name,
        role_id=admin.role_id,
        status=admin.status,
        last_login=admin.last_login,
        created_at=admin.created_at
    )


@router.delete("/users/{admin_id}", response_model=DeleteAdminUserResponse)
@require_governance(
    action_complexity=ActionComplexity.CRITICAL,
    action_name="delete_admin_user",
    feature="admin"
)
async def delete_admin_user(
    admin_id: str,
    http_request: Request,
    current_admin: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Delete admin user

    Permanently deletes an admin user.
    Requires super_admin role.

    **Governance**: Agent-based deletion requires AUTONOMOUS maturity (CRITICAL).
    - Admin user deletion is a critical action
    - Requires AUTONOMOUS maturity for agents
    """
    admin = db.query(AdminUser).filter(AdminUser.id == admin_id).first()

    if not admin:
        raise router.not_found_error("AdminUser", admin_id)

    deleted_email = admin.email
    db.delete(admin)
    db.commit()

    logger.info(f"Admin user deleted: {admin_id} ({deleted_email}) by {current_admin.id}")
    return DeleteAdminUserResponse(message="Admin user deleted successfully")


@router.patch("/users/{admin_id}/last-login", response_model=UpdateLastLoginResponse)
async def update_admin_last_login(
    admin_id: str,
    current_admin: User = Depends(require_super_admin),
    db: Session = Depends(get_db)
):
    """
    Update admin user's last login timestamp

    Called after successful admin authentication.
    """
    # Find admin user
    admin = db.query(AdminUser).filter(AdminUser.id == admin_id).first()
    if not admin:
        raise router.not_found_error("AdminUser", admin_id)

    # Update last login
    admin.last_login = datetime.utcnow()
    db.commit()

    return UpdateLastLoginResponse(message="Last login updated")


# Role Management Endpoints
@router.get("/roles", response_model=List[AdminRoleResponse])
async def list_admin_roles(
    current_admin: User = Depends(require_super_admin),
    db: Session = Depends(get_db)
):
    """
    List all admin roles

    Returns all available admin roles with their permissions.
    """
    roles = db.query(AdminRole).all()

    return [
        AdminRoleResponse(
            id=role.id,
            name=role.name,
            permissions=role.permissions or {},
            description=role.description
        )
        for role in roles
    ]


@router.get("/roles/{role_id}", response_model=AdminRoleResponse)
async def get_admin_role(
    role_id: str,
    current_admin: User = Depends(require_super_admin),
    db: Session = Depends(get_db)
):
    """
    Get specific admin role by ID

    Returns detailed role information including permissions.
    """
    role = db.query(AdminRole).filter(AdminRole.id == role_id).first()

    if not role:
        raise router.not_found_error("AdminRole", role_id)

    return AdminRoleResponse(
        id=role.id,
        name=role.name,
        permissions=role.permissions or {},
        description=role.description
    )


@router.post("/roles", response_model=AdminRoleResponse, status_code=status.HTTP_201_CREATED)
@require_governance(
    action_complexity=ActionComplexity.CRITICAL,
    action_name="create_admin_role",
    feature="admin"
)
async def create_admin_role(
    request: CreateAdminRoleRequest,
    http_request: Request,
    current_admin: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Create a new admin role

    Creates a new admin role with specified permissions.
    Role names must be unique.

    **Governance**: Agent-based creation requires AUTONOMOUS maturity (CRITICAL).
    - Admin role creation is a critical action
    - Requires AUTONOMOUS maturity for agents
    """
    # Check if role name already exists
    existing = db.query(AdminRole).filter(AdminRole.name == request.name).first()
    if existing:
        raise router.conflict_error(
            message="Role with this name already exists",
            conflicting_resource=request.name,
            details={"field": "name", "name": request.name}
        )

    role = AdminRole(
        name=request.name,
        permissions=request.permissions,
        description=request.description
    )

    db.add(role)
    db.commit()
    db.refresh(role)

    return AdminRoleResponse(
        id=role.id,
        name=role.name,
        permissions=role.permissions,
        description=role.description
    )


@router.patch("/roles/{role_id}", response_model=AdminRoleResponse)
async def update_admin_role(
    role_id: str,
    request: UpdateAdminRoleRequest,
    current_admin: User = Depends(require_super_admin),
    db: Session = Depends(get_db)
):
    """
    Update admin role

    Updates role information. Only provided fields are updated.
    """
    role = db.query(AdminRole).filter(AdminRole.id == role_id).first()

    if not role:
        raise router.not_found_error("AdminRole", role_id)

    # Check if new name conflicts with existing role
    if request.name is not None and request.name != role.name:
        existing = db.query(AdminRole).filter(
            AdminRole.name == request.name,
            AdminRole.id != role_id
        ).first()
        if existing:
            raise router.conflict_error(
                message="Role with this name already exists",
                conflicting_resource=request.name,
                details={"field": "name", "name": request.name}
            )
        role.name = request.name

    # Update other fields
    if request.permissions is not None:
        role.permissions = request.permissions
    if request.description is not None:
        role.description = request.description

    db.commit()
    db.refresh(role)

    return AdminRoleResponse(
        id=role.id,
        name=role.name,
        permissions=role.permissions,
        description=role.description
    )


@router.delete("/roles/{role_id}", response_model=DeleteAdminRoleResponse)
@require_governance(
    action_complexity=ActionComplexity.CRITICAL,
    action_name="delete_admin_role",
    feature="admin"
)
async def delete_admin_role(
    role_id: str,
    http_request: Request,
    current_admin: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Delete admin role

    Permanently deletes an admin role.
    Fails if the role is currently assigned to any admin users.

    **Governance**: Agent-based deletion requires AUTONOMOUS maturity (CRITICAL).
    - Admin role deletion is a critical action
    - Requires AUTONOMOUS maturity for agents
    """
    role = db.query(AdminRole).filter(AdminRole.id == role_id).first()

    if not role:
        raise router.not_found_error("AdminRole", role_id)

    # Check if role is in use
    users_with_role = db.query(AdminUser).filter(AdminUser.role_id == role_id).count()
    if users_with_role > 0:
        raise router.conflict_error(
            message=f"Cannot delete role: {users_with_role} admin user(s) still assigned to this role",
            details={"users_count": users_with_role, "role_id": role_id}
        )

    db.delete(role)
    db.commit()

    return DeleteAdminRoleResponse(message="Admin role deleted successfully")


# ============================================================================
# WebSocket Management Endpoints
# ============================================================================

class WebSocketStatusResponse(BaseModel):
    """WebSocket status response"""
    connected: bool
    ws_url: Optional[str] = None
    last_connected_at: Optional[str] = None
    last_message_at: Optional[str] = None
    reconnect_attempts: int = 0
    consecutive_failures: int = 0
    last_disconnect_reason: Optional[str] = None
    fallback_to_polling: bool = False
    rate_limit_messages_per_sec: int = 100


class WebSocketReconnectResponse(BaseModel):
    """WebSocket reconnect response"""
    reconnect_triggered: bool
    message: str


class WebSocketToggleResponse(BaseModel):
    """WebSocket toggle response"""
    success: bool
    websocket_enabled: Optional[bool] = None
    message: str


@router.get("/websocket/status", response_model=WebSocketStatusResponse)
async def get_websocket_status(
    current_user: User = Depends(require_super_admin),
    db: Session = Depends(get_db)
):
    """
    Get WebSocket connection status (ADMIN ONLY)

    Returns current WebSocket connection details including:
    - Connection status (connected/disconnected)
    - Last connection and message timestamps
    - Reconnect attempts and failure reasons
    - Fallback mode status

    **Security**: Requires super_admin role
    """
    # Check governance (AUTONOMOUS required)
    from core.agent_governance_service import GovernanceCache
    governance_cache = GovernanceCache()

    # Get user's maturity level
    user_maturity = "AUTONOMOUS"  # Default to AUTONOMOUS for human users

    if user_maturity != "AUTONOMOUS":
        raise router.permission_denied_error(
            action="get_websocket_status",
            resource="WebSocket",
            details={"required_maturity": "AUTONOMOUS", "actual_maturity": user_maturity}
        )

    # Get WebSocket state from database
    from core.models import WebSocketState
    ws_state = db.query(WebSocketState).first()

    if not ws_state:
        return WebSocketStatusResponse(
            connected=False,
            reconnect_attempts=0,
            consecutive_failures=0,
            rate_limit_messages_per_sec=100
        )

    return WebSocketStatusResponse(
        connected=ws_state.connected,
        last_connected_at=ws_state.last_connected_at.isoformat() if ws_state.last_connected_at else None,
        last_message_at=ws_state.last_message_at.isoformat() if ws_state.last_message_at else None,
        reconnect_attempts=ws_state.reconnect_attempts,
        consecutive_failures=ws_state.consecutive_failures,
        last_disconnect_reason=ws_state.disconnect_reason,
        fallback_to_polling=ws_state.fallback_to_polling,
        rate_limit_messages_per_sec=100
    )


@router.post("/websocket/reconnect", response_model=WebSocketReconnectResponse)
@require_governance(
    action_complexity=ActionComplexity.HIGH,
    action_name="websocket_reconnect",
    feature="admin"
)
async def trigger_websocket_reconnect(
    http_request: Request,
    current_user: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Force WebSocket reconnection (ADMIN ONLY)

    Triggers immediate WebSocket reconnection attempt.
    If currently connected, disconnects and reconnects.

    **Security**: Requires super_admin role
    **Governance**: Requires AUTONOMOUS maturity (HIGH) for AI agents
    """
    # Log audit trail
    logger.info(f"WebSocket reconnect triggered by {current_user.id} (agent: {agent_id})")

    # Get WebSocket client instance (would need to be stored globally)
    # For now, just update database state to trigger reconnect
    from core.models import WebSocketState
    ws_state = db.query(WebSocketState).first()

    if not ws_state:
        ws_state = WebSocketState(id=1)
        db.add(ws_state)

    # Reset reconnect attempts to allow immediate reconnect
    ws_state.reconnect_attempts = 0
    ws_state.consecutive_failures = 0
    ws_state.fallback_to_polling = False
    db.commit()

    return WebSocketReconnectResponse(
        reconnect_triggered=True,
        message="WebSocket reconnection triggered. Reconnect will attempt on next cycle."
    )


@router.post("/websocket/disable", response_model=WebSocketToggleResponse)
@require_governance(
    action_complexity=ActionComplexity.HIGH,
    action_name="websocket_disable",
    feature="admin"
)
async def disable_websocket(
    http_request: Request,
    current_user: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Disable WebSocket (use polling only) - ADMIN ONLY

    Disables WebSocket connection and switches to polling-only mode.
    Useful for troubleshooting or if WebSocket is causing issues.

    **Security**: Requires super_admin role
    **Governance**: Requires AUTONOMOUS maturity (HIGH) for AI agents
    """
    # Log audit trail
    logger.info(f"WebSocket disabled by {current_user.id} (agent: {agent_id})")

    from core.models import WebSocketState
    ws_state = db.query(WebSocketState).first()

    if not ws_state:
        ws_state = WebSocketState(id=1)
        db.add(ws_state)

    ws_state.fallback_to_polling = True
    ws_state.fallback_started_at = datetime.now()
    ws_state.connected = False
    ws_state.disconnect_reason = "disabled_by_admin"
    db.commit()

    return WebSocketToggleResponse(
        success=True,
        websocket_enabled=False,
        message="WebSocket disabled. System will use polling for sync."
    )


@router.post("/websocket/enable", response_model=WebSocketToggleResponse)
@require_governance(
    action_complexity=ActionComplexity.HIGH,
    action_name="websocket_enable",
    feature="admin"
)
async def enable_websocket(
    http_request: Request,
    current_user: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Re-enable WebSocket - ADMIN ONLY

    Re-enables WebSocket connection after it was disabled.
    System will attempt to reconnect to WebSocket server.

    **Security**: Requires super_admin role
    **Governance**: Requires AUTONOMOUS maturity (HIGH) for AI agents
    """
    # Log audit trail
    logger.info(f"WebSocket enabled by {current_user.id} (agent: {agent_id})")

    from core.models import WebSocketState
    ws_state = db.query(WebSocketState).first()

    if not ws_state:
        ws_state = WebSocketState(id=1)
        db.add(ws_state)

    ws_state.fallback_to_polling = False
    ws_state.next_ws_attempt_at = None
    ws_state.reconnect_attempts = 0
    db.commit()

    return WebSocketToggleResponse(
        success=True,
        websocket_enabled=True,
        message="WebSocket enabled. Reconnection will be attempted."
    )


# ============================================================================
# Rating Sync Admin Endpoints (Phase 61 Plan 02)
# ============================================================================

class RatingSyncRequest(BaseModel):
    """Request to trigger rating sync"""
    upload_all: bool = Field(default=False, description="Upload all ratings (default: only pending)")


class RatingSyncResponse(BaseModel):
    """Response from rating sync"""
    success: bool
    uploaded: int
    failed: int
    skipped: int
    pending_count: int
    message: Optional[str] = None
    error: Optional[str] = None


class FailedRatingUploadResponse(BaseModel):
    """Failed rating upload details"""
    id: str
    rating_id: str
    error_message: str
    failed_at: datetime
    retry_count: int
    last_retry_at: Optional[datetime]

    model_config = ConfigDict(from_attributes=True)


class RetryRatingUploadResponse(BaseModel):
    """Response from retrying failed upload"""
    success: bool
    message: str
    retry_triggered: bool


@router.post("/sync/ratings", response_model=RatingSyncResponse)
@require_governance(
    action_complexity=ActionComplexity.HIGH,
    action_name="rating_sync",
    feature="admin"
)
async def trigger_rating_sync(
    request: RatingSyncRequest,
    http_request: Request,
    current_user: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Trigger manual rating sync with Atom SaaS - ADMIN ONLY

    Manually trigger rating sync to upload pending ratings to Atom SaaS.
    Returns 503 if sync is already in progress.

    **Security**: Requires super_admin role
    **Governance**: Requires AUTONOMOUS maturity (HIGH) for AI agents

    Args:
        request: Sync request with upload_all flag
        current_user: Authenticated super_admin user
        db: Database session
        agent_id: Agent ID if triggered by agent

    Returns:
        RatingSyncResponse with upload counts
    """
    from core.rating_sync_service import RatingSyncService
    from core.atom_saas_client import AtomSaaSClient

    # Log audit trail
    logger.info(
        f"Rating sync triggered by {current_user.id} "
        f"(agent: {agent_id}, upload_all: {request.upload_all})"
    )

    # Create sync service
    client = AtomSaaSClient()
    sync_service = RatingSyncService(db, client)

    # Check if sync is already in progress
    if sync_service._sync_in_progress:
        from fastapi import status
        raise router.api_error(
            error_code="RATING_SYNC_IN_PROGRESS",
            message="Rating sync is already in progress",
            http_status=status.HTTP_503_SERVICE_UNAVAILABLE
        )

    # Get pending count before sync
    pending_count = len(sync_service.get_pending_ratings())

    # Trigger sync
    import asyncio
    result = await sync_service.sync_ratings(upload_all=request.upload_all)

    logger.info(
        f"Rating sync completed for {current_user.id}: "
        f"{result.get('uploaded')} uploaded, {result.get('failed')} failed"
    )

    return RatingSyncResponse(
        success=result.get("success", False),
        uploaded=result.get("uploaded", 0),
        failed=result.get("failed", 0),
        skipped=result.get("skipped", 0),
        pending_count=pending_count,
        message=result.get("message"),
        error=result.get("error")
    )


@router.get("/ratings/failed-uploads", response_model=List[FailedRatingUploadResponse])
async def get_failed_rating_uploads(
    current_user: User = Depends(require_super_admin),
    db: Session = Depends(get_db)
):
    """
    Get failed rating uploads (dead letter queue) - ADMIN ONLY

    Returns list of failed rating uploads for inspection and manual retry.
    Failed uploads are stored when rating sync encounters errors.

    **Security**: Requires super_admin role
    """
    from core.agent_governance_service import GovernanceCache
    governance_cache = GovernanceCache()

    # Get user's maturity level
    user_maturity = "AUTONOMOUS"  # Default to AUTONOMOUS for human users

    if user_maturity != "AUTONOMOUS":
        raise router.permission_denied_error(
            action="get_failed_rating_uploads",
            resource="RatingUpload",
            details={"required_maturity": "AUTONOMOUS", "actual_maturity": user_maturity}
        )

    from core.models import FailedRatingUpload

    # Query failed uploads, ordered by failed_at desc
    failed_uploads = (
        db.query(FailedRatingUpload)
        .order_by(FailedRatingUpload.failed_at.desc())
        .limit(100)  # Pagination limit
        .all()
    )

    return [
        FailedRatingUploadResponse(
            id=failed.id,
            rating_id=failed.rating_id,
            error_message=failed.error_message,
            failed_at=failed.failed_at,
            retry_count=failed.retry_count,
            last_retry_at=failed.last_retry_at
        )
        for failed in failed_uploads
    ]


@router.post("/ratings/failed-uploads/{failed_id}/retry", response_model=RetryRatingUploadResponse)
@require_governance(
    action_complexity=ActionComplexity.HIGH,
    action_name="retry_rating_upload",
    feature="admin"
)
async def retry_failed_rating_upload(
    failed_id: str,
    http_request: Request,
    current_user: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Retry failed rating upload

    Manually retry a failed rating upload from the dead letter queue.
    Deletes the failed upload record on success.

    **Governance**: Requires AUTONOMOUS maturity (HIGH).
    """
    from core.models import FailedRatingUpload, SkillRating
    from core.rating_sync_service import RatingSyncService
    from core.atom_saas_client import AtomSaaSClient

    # Log audit trail
    logger.info(
        f"Retry failed rating upload {failed_id} by {current_user.id} "
        f"(agent: {agent_id})"
    )

    # Fetch failed upload record
    failed = (
        db.query(FailedRatingUpload)
        .filter(FailedRatingUpload.id == failed_id)
        .first()
    )

    if not failed:
        raise router.not_found_error("FailedRatingUpload", failed_id)

    # Fetch the rating
    rating = (
        db.query(SkillRating)
        .filter(SkillRating.id == failed.rating_id)
        .first()
    )

    if not rating:
        # Rating was deleted, remove failed record
        db.delete(failed)
        db.commit()
        return RetryRatingUploadResponse(
            success=False,
            message="Rating no longer exists, failed record removed",
            retry_triggered=False
        )

    # Create sync service and retry upload
    client = AtomSaaSClient()
    sync_service = RatingSyncService(db, client)

    # Upload single rating
    import asyncio
    result = await sync_service.upload_rating(rating)

    if result.get("success"):
        # Success - mark as synced and remove failed record
        remote_id = result.get("rating_id")
        if remote_id:
            sync_service.mark_as_synced(rating.id, remote_id)

        db.delete(failed)
        db.commit()

        logger.info(f"Retry successful for failed upload {failed_id}")
        return RetryRatingUploadResponse(
            success=True,
            message=f"Rating uploaded successfully (remote_id: {remote_id})",
            retry_triggered=True
        )
    else:
        # Failed again - increment retry count
        failed.retry_count += 1
        failed.last_retry_at = datetime.now()
        failed.error_message = result.get("error", "Unknown error")
        db.commit()

        logger.error(f"Retry failed for {failed_id}: {result.get('error')}")
        return RetryRatingUploadResponse(
            success=False,
            message=f"Retry failed: {result.get('error')}",
            retry_triggered=True
        )


# ============================================================================
# Conflict Management Endpoints
# ============================================================================

class ConflictLogResponse(BaseModel):
    """Conflict log entry response"""
    id: int
    skill_id: str
    conflict_type: str
    severity: str
    local_data: dict
    remote_data: dict
    resolution_strategy: Optional[str]
    resolved_data: Optional[dict]
    resolved_at: Optional[datetime]
    resolved_by: Optional[str]
    created_at: datetime

    model_config = ConfigDict(from_attributes=True)


class ConflictListResponse(BaseModel):
    """Paginated list of conflicts"""
    conflicts: List[ConflictLogResponse]
    total_count: int
    page: int
    page_size: int


class ResolveConflictRequest(BaseModel):
    """Request to resolve a conflict"""
    strategy: str = Field(..., description="Resolution strategy: remote_wins, local_wins, merge")
    resolved_by: str = Field(..., description="User or system resolving the conflict")


class ResolveConflictResponse(BaseModel):
    """Response after resolving conflict"""
    success: bool
    message: str
    resolved_data: Optional[dict] = None


class BulkResolveConflictsRequest(BaseModel):
    """Request to bulk resolve conflicts"""
    conflict_ids: List[int] = Field(..., min_items=1, max_items=100, description="List of conflict IDs to resolve (max 100)")
    strategy: str = Field(..., description="Resolution strategy: remote_wins, local_wins, merge")
    resolved_by: str = Field(..., description="User or system resolving the conflicts")


class BulkResolveConflictsResponse(BaseModel):
    """Response after bulk resolving conflicts"""
    success: bool
    message: str
    resolved_count: int
    failed_count: int
    errors: List[str] = []


@router.get("/conflicts", response_model=ConflictListResponse)
@require_governance(
    action_complexity=ActionComplexity.HIGH,
    action_name="list_conflicts",
    feature="admin"
)
async def list_conflicts(
    severity: Optional[str] = None,
    conflict_type: Optional[str] = None,
    page: int = 1,
    page_size: int = 50,
    current_user: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    List unresolved conflicts - ADMIN ONLY

    Returns paginated list of unresolved skill sync conflicts.
    Can filter by severity and conflict type.

    **Security**: Requires super_admin role
    **Governance**: Requires AUTONOMOUS maturity (HIGH) for AI agents
    """
    from core.models import ConflictLog
    from core.conflict_resolution_service import ConflictResolutionService

    # Log audit trail
    logger.info(
        f"List conflicts by {current_user.id} (agent: {agent_id}) "
        f"filters: severity={severity}, type={conflict_type}"
    )

    resolver = ConflictResolutionService(db)

    # Get unresolved conflicts
    conflicts = resolver.get_unresolved_conflicts(
        severity=severity,
        conflict_type=conflict_type,
        limit=page_size
    )

    # Calculate pagination
    total_count = len(conflicts)
    start_idx = (page - 1) * page_size
    end_idx = start_idx + page_size
    paginated_conflicts = conflicts[start_idx:end_idx]

    return ConflictListResponse(
        conflicts=[
            ConflictLogResponse(
                id=c.id,
                skill_id=c.skill_id,
                conflict_type=c.conflict_type,
                severity=c.severity,
                local_data=c.local_data,
                remote_data=c.remote_data,
                resolution_strategy=c.resolution_strategy,
                resolved_data=c.resolved_data,
                resolved_at=c.resolved_at,
                resolved_by=c.resolved_by,
                created_at=c.created_at
            )
            for c in paginated_conflicts
        ],
        total_count=total_count,
        page=page,
        page_size=page_size
    )


@router.get("/conflicts/{conflict_id}", response_model=ConflictLogResponse)
@require_governance(
    action_complexity=ActionComplexity.HIGH,
    action_name="get_conflict",
    feature="admin"
)
async def get_conflict(
    conflict_id: int,
    current_user: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Get conflict details by ID - ADMIN ONLY

    Returns full conflict data including local/remote skill data
    and a diff summary of what changed.

    **Security**: Requires super_admin role
    **Governance**: Requires AUTONOMOUS maturity (HIGH) for AI agents
    """
    from core.conflict_resolution_service import ConflictResolutionService

    # Log audit trail
    logger.info(
        f"Get conflict {conflict_id} by {current_user.id} (agent: {agent_id})"
    )

    resolver = ConflictResolutionService(db)
    conflict = resolver.get_conflict_by_id(conflict_id)

    if not conflict:
        raise router.not_found_error("ConflictLog", conflict_id)

    return ConflictLogResponse(
        id=conflict.id,
        skill_id=conflict.skill_id,
        conflict_type=conflict.conflict_type,
        severity=conflict.severity,
        local_data=conflict.local_data,
        remote_data=conflict.remote_data,
        resolution_strategy=conflict.resolution_strategy,
        resolved_data=conflict.resolved_data,
        resolved_at=conflict.resolved_at,
        resolved_by=conflict.resolved_by,
        created_at=conflict.created_at
    )


@router.post("/conflicts/{conflict_id}/resolve", response_model=ResolveConflictResponse)
@require_governance(
    action_complexity=ActionComplexity.HIGH,
    action_name="resolve_conflict",
    feature="admin"
)
async def resolve_conflict(
    conflict_id: int,
    request: ResolveConflictRequest,
    http_request: Request,
    current_user: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Resolve a conflict - ADMIN ONLY

    Applies the specified resolution strategy to a conflict.
    Updates the ConflictLog and triggers cache update with resolved data.

    Strategies:
    - remote_wins: Use Atom SaaS skill data
    - local_wins: Use local skill data
    - merge: Intelligently merge fields

    **Security**: Requires super_admin role
    **Governance**: Requires AUTONOMOUS maturity (HIGH) for AI agents
    """
    from core.conflict_resolution_service import ConflictResolutionService

    # Validate strategy
    valid_strategies = ["remote_wins", "local_wins", "merge"]
    if request.strategy not in valid_strategies:
        raise router.validation_error(
            "Invalid strategy",
            details={"valid_strategies": valid_strategies, "provided": request.strategy}
        )

    # Log audit trail
    logger.info(
        f"Resolve conflict {conflict_id} by {current_user.id} "
        f"(agent: {agent_id}) using {request.strategy}"
    )

    resolver = ConflictResolutionService(db)

    # Resolve conflict
    resolved_data = resolver.resolve_conflict(
        conflict_id=conflict_id,
        strategy=request.strategy,
        resolved_by=request.resolved_by
    )

    if resolved_data is None and request.strategy != "manual":
        return ResolveConflictResponse(
            success=False,
            message="Failed to resolve conflict"
        )

    # Update cache with resolved data
    if resolved_data:
        from core.models import SkillCache
        from datetime import timezone, timedelta

        skill_id = resolved_data.get("skill_id") or resolved_data.get("id")
        if skill_id:
            # Calculate expiry
            expires_at = datetime.now(timezone.utc).replace(
                hour=23, minute=59, second=59, microsecond=0
            )

            # Update cache
            existing = db.query(SkillCache).filter(
                SkillCache.skill_id == skill_id
            ).first()

            if existing:
                existing.skill_data = resolved_data
                existing.expires_at = expires_at
                db.commit()

    return ResolveConflictResponse(
        success=True,
        message=f"Conflict resolved using {request.strategy}",
        resolved_data=resolved_data
    )


@router.post("/conflicts/bulk-resolve", response_model=BulkResolveConflictsResponse)
@require_governance(
    action_complexity=ActionComplexity.HIGH,
    action_name="bulk_resolve_conflicts",
    feature="admin"
)
async def bulk_resolve_conflicts(
    request: BulkResolveConflictsRequest,
    http_request: Request,
    current_user: User = Depends(require_super_admin),
    db: Session = Depends(get_db),
    agent_id: Optional[str] = None
):
    """
    Bulk resolve multiple conflicts - ADMIN ONLY

    Applies the same resolution strategy to multiple conflicts.
    Uses transaction for atomicity (all or nothing).

    Max 100 conflicts per request.

    **Security**: Requires super_admin role
    **Governance**: Requires AUTONOMOUS maturity (HIGH) for AI agents
    """
    from core.conflict_resolution_service import ConflictResolutionService

    # Validate strategy
    valid_strategies = ["remote_wins", "local_wins", "merge"]
    if request.strategy not in valid_strategies:
        raise router.validation_error(
            "Invalid strategy",
            details={"valid_strategies": valid_strategies, "provided": request.strategy}
        )

    # Log audit trail
    logger.info(
        f"Bulk resolve {len(request.conflict_ids)} conflicts by {current_user.id} "
        f"(agent: {agent_id}) using {request.strategy}"
    )

    resolver = ConflictResolutionService(db)
    resolved_count = 0
    failed_count = 0
    errors = []

    # Resolve each conflict
    for conflict_id in request.conflict_ids:
        try:
            resolved_data = resolver.resolve_conflict(
                conflict_id=conflict_id,
                strategy=request.strategy,
                resolved_by=request.resolved_by
            )

            if resolved_data or request.strategy == "manual":
                resolved_count += 1
            else:
                failed_count += 1
                errors.append(f"Conflict {conflict_id}: Failed to resolve")

        except Exception as e:
            failed_count += 1
            errors.append(f"Conflict {conflict_id}: {str(e)}")

    return BulkResolveConflictsResponse(
        success=(failed_count == 0),
        message=f"Resolved {resolved_count} conflicts, {failed_count} failed",
        resolved_count=resolved_count,
        failed_count=failed_count,
        errors=errors
    )