brain/app/api/admin.py

"""
Phase 3 Admin-facing API endpoints.
Handles admin operations: health, allocation runs, assignments, metrics, appeals, overrides, config.
"""

from datetime import date

from fastapi import APIRouter, Depends, HTTPException, Query, status
from sqlalchemy.ext.asyncio import AsyncSession
from uuid import UUID

from app.database import get_db
from app.schemas.admin import (
    HealthResponse,
    AllocationRunsListResponse,
    AdminAssignmentsListResponse,
    FairnessMetricsResponse,
    WorkloadHeatmapResponse,
    DriverHistoryResponse,
    AppealsListResponse,
    AppealDecisionRequest,
    AppealDecisionResponse,
    ManualOverrideRequest,
    ManualOverrideResponse,
    FairnessConfigRequest,
    FairnessConfigResponse,
    AgentTimelineResponse,
    DriverAllocationStoryResponse,
)
from app.services.admin_service import (
    get_system_health,
    get_allocation_runs,
    get_assignments_paginated,
    get_fairness_metrics_series,
    get_workload_heatmap,
    get_driver_history,
    list_appeals,
    decide_appeal,
    perform_manual_override,
    get_active_fairness_config,
    create_fairness_config,
    get_agent_timeline,
    get_driver_allocation_story,
)

router = APIRouter(prefix="/admin", tags=["Admin"])


@router.get(
    "/health",
    response_model=HealthResponse,
    summary="System health check",
    description="Get system health status including database and latest allocation run.",
)
async def health_check(
    db: AsyncSession = Depends(get_db),
) -> HealthResponse:
    """Check system health."""
    return await get_system_health(db)


@router.get(
    "/allocation_runs",
    response_model=AllocationRunsListResponse,
    summary="List allocation runs",
    description="Get allocation runs for a specific date.",
)
async def get_allocation_runs_endpoint(
    date: date = Query(..., description="Date to query"),
    db: AsyncSession = Depends(get_db),
) -> AllocationRunsListResponse:
    """List allocation runs for date."""
    return await get_allocation_runs(db, date)


@router.get(
    "/assignments",
    response_model=AdminAssignmentsListResponse,
    summary="List assignments",
    description="Get paginated list of assignments with filters.",
)
async def get_assignments_endpoint(
    date: date = Query(..., description="Date to query"),
    driver_id: UUID = Query(default=None, description="Filter by driver"),
    min_fairness: float = Query(default=None, ge=0, le=1, description="Minimum fairness score"),
    max_fairness: float = Query(default=None, ge=0, le=1, description="Maximum fairness score"),
    page: int = Query(default=1, ge=1, description="Page number"),
    page_size: int = Query(default=50, ge=1, le=100, description="Items per page"),
    db: AsyncSession = Depends(get_db),
) -> AdminAssignmentsListResponse:
    """Get paginated assignments."""
    return await get_assignments_paginated(
        db, date, driver_id, min_fairness, max_fairness, page, page_size
    )


@router.get(
    "/metrics/fairness",
    response_model=FairnessMetricsResponse,
    summary="Fairness metrics time series",
    description="Get fairness metrics over a date range.",
)
async def get_fairness_metrics_endpoint(
    start_date: date = Query(..., description="Start date"),
    end_date: date = Query(..., description="End date"),
    db: AsyncSession = Depends(get_db),
) -> FairnessMetricsResponse:
    """Get fairness metrics time series."""
    return await get_fairness_metrics_series(db, start_date, end_date)


@router.get(
    "/workload_heatmap",
    response_model=WorkloadHeatmapResponse,
    summary="Workload heatmap",
    description="Get workload heatmap data for visualization.",
)
async def get_heatmap_endpoint(
    start_date: date = Query(..., description="Start date"),
    end_date: date = Query(..., description="End date"),
    db: AsyncSession = Depends(get_db),
) -> WorkloadHeatmapResponse:
    """Get workload heatmap data."""
    return await get_workload_heatmap(db, start_date, end_date)


@router.get(
    "/driver/{driver_id}/history",
    response_model=DriverHistoryResponse,
    summary="Driver history",
    description="Get detailed driver history including appeals and overrides.",
)
async def get_driver_history_endpoint(
    driver_id: UUID,
    window_days: int = Query(default=30, ge=1, le=365, description="Days to look back"),
    db: AsyncSession = Depends(get_db),
) -> DriverHistoryResponse:
    """Get driver history."""
    result = await get_driver_history(db, driver_id, window_days)
    if not result:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Driver not found",
        )
    return result


@router.get(
    "/appeals",
    response_model=AppealsListResponse,
    summary="List appeals",
    description="Get list of appeals with optional status filter.",
)
async def get_appeals_endpoint(
    status: str = Query(default=None, description="Filter by status (PENDING, APPROVED, REJECTED, RESOLVED)"),
    db: AsyncSession = Depends(get_db),
) -> AppealsListResponse:
    """List appeals."""
    return await list_appeals(db, status)


@router.post(
    "/appeals/{appeal_id}/decision",
    response_model=AppealDecisionResponse,
    summary="Decide appeal",
    description="Update appeal status with admin decision.",
)
async def decide_appeal_endpoint(
    appeal_id: UUID,
    request: AppealDecisionRequest,
    db: AsyncSession = Depends(get_db),
) -> AppealDecisionResponse:
    """Make decision on an appeal."""
    try:
        result = await decide_appeal(db, appeal_id, request.status, request.admin_note)
        if not result:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail="Appeal not found",
            )
        await db.commit()
        return result
    except ValueError as e:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail=str(e),
        )


@router.post(
    "/manual_override",
    response_model=ManualOverrideResponse,
    summary="Manual override",
    description="Manually reassign a route from one driver to another.",
)
async def manual_override_endpoint(
    request: ManualOverrideRequest,
    db: AsyncSession = Depends(get_db),
) -> ManualOverrideResponse:
    """Perform manual route override."""
    try:
        result = await perform_manual_override(
            db=db,
            allocation_run_id=request.allocation_run_id,
            old_driver_id=request.old_driver_id,
            new_driver_id=request.new_driver_id,
            route_id=request.route_id,
            reason=request.reason,
        )
        await db.commit()
        return result
    except ValueError as e:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail=str(e),
        )


@router.get(
    "/fairness_config",
    response_model=FairnessConfigResponse,
    summary="Get fairness config",
    description="Get the currently active fairness configuration.",
)
async def get_fairness_config_endpoint(
    db: AsyncSession = Depends(get_db),
) -> FairnessConfigResponse:
    """Get active fairness config."""
    result = await get_active_fairness_config(db)
    if not result:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="No active fairness config found",
        )
    return result


@router.post(
    "/fairness_config",
    response_model=FairnessConfigResponse,
    status_code=status.HTTP_201_CREATED,
    summary="Create fairness config",
    description="Create new fairness config and deactivate existing ones.",
)
async def create_fairness_config_endpoint(
    request: FairnessConfigRequest,
    db: AsyncSession = Depends(get_db),
) -> FairnessConfigResponse:
    """Create new fairness config."""
    result = await create_fairness_config(
        db=db,
        workload_weight_packages=request.workload_weight_packages,
        workload_weight_weight_kg=request.workload_weight_weight_kg,
        workload_weight_difficulty=request.workload_weight_difficulty,
        workload_weight_time=request.workload_weight_time,
        gini_threshold=request.gini_threshold,
        stddev_threshold=request.stddev_threshold,
        max_gap_threshold=request.max_gap_threshold,
        recovery_mode_enabled=request.recovery_mode_enabled,
    )
    await db.commit()
    return result


@router.get(
    "/agent_timeline",
    response_model=AgentTimelineResponse,
    summary="Agent timeline",
    description="Get agent decision logs for an allocation run.",
)
async def get_agent_timeline_endpoint(
    allocation_run_id: UUID = Query(..., description="Allocation run ID"),
    db: AsyncSession = Depends(get_db),
) -> AgentTimelineResponse:
    """Get agent timeline for allocation run."""
    return await get_agent_timeline(db, allocation_run_id)


@router.get(
    "/driver_allocation_story",
    response_model=DriverAllocationStoryResponse,
    summary="Driver allocation story",
    description="Get complete allocation story for a driver on a specific date.",
)
async def get_driver_allocation_story_endpoint(
    driver_id: UUID = Query(..., description="Driver ID"),
    date: date = Query(..., description="Date to query (ISO format)"),
    db: AsyncSession = Depends(get_db),
) -> DriverAllocationStoryResponse:
    """Get driver allocation story for a specific date."""
    result = await get_driver_allocation_story(db, driver_id, date)
    if not result:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="No assignment found for driver on given date",
        )
    return result