Refine health checks and add polling animation

app/backend/operations/health/router.py

@@ -0,0 +1,74 @@
+"""Health endpoints."""
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import PlainTextResponse
+
+from core.config import Settings, get_settings
+from operations.health.schemas import HealthStatus
+from operations.health.service import get_detailed_health, readiness_check
+
+router = APIRouter(prefix="/health", tags=["health"])
+
+
+@router.get(
+    "/live",
+    summary="Liveness Probe",
+    response_class=PlainTextResponse,
+    status_code=200,
+)
+def liveness() -> str:
+    """
+    **Liveness Probe:** Confirms the application process is running and responsive.
+
+    This endpoint is used by automated systems (like Kubernetes) to determine if
+    the instance should be kept running or restarted. It must be extremely lightweight,
+    performing no deep checks on external dependencies.
+
+    **Success Response:** HTTP 200 OK with "live" body.  
+    **Failure Response:** Endpoint timeout (no response).
+    """
+    return "live"
+
+
+@router.get(
+    "/ready",
+    summary="Readiness Probe",
+    response_class=PlainTextResponse,
+    status_code=200,
+)
+async def readiness() -> str:
+    """
+    **Readiness Probe:** Determines if the application can accept user traffic.
+
+    This endpoint is used by load balancers to route traffic. It performs deep checks
+    on all critical dependencies (e.g., database, message queue).
+
+    **Success Response:** HTTP 200 OK with "ready" body.  
+    **Failure Response:** HTTP 503 Service Unavailable if any critical dependency fails.
+    """
+    ok = await readiness_check()
+    if not ok:
+        raise HTTPException(status_code=503, detail="not ready")
+
+    return "ready"
+
+
+@router.get(
+    "",
+    summary="Detailed Health Status Page",
+    response_model=HealthStatus,
+    status_code=200,
+)
+async def detailed_health(settings: Settings = Depends(get_settings)) -> HealthStatus:
+    """
+    **Detailed Status Page:** Provides granular health information for human operators.
+
+    This endpoint runs all readiness checks and returns a structured JSON object.
+    The top-level HTTP status code reflects the overall application health (200 OK or 503 Service Unavailable).
+    """
+    detailed_health = await get_detailed_health(settings)
+
+    if detailed_health.status != "pass":
+        raise HTTPException(status_code=503, detail="not ready")
+
+    return detailed_health