# Module Contracts: Dashboard Health Windows

## Backend Contracts

# [DEF:ValidationPolicyModel:Class]
# @TIER: STANDARD
# @SEMANTICS: SQLAlchemy, Model
# @PURPOSE: Database model for storing validation scheduling rules.
# @LAYER: Domain
# @RELATION: DEPENDS_ON -> SQLAlchemy declarative base
# @PRE: Policy payload contains valid window_start and window_end strings.
# @POST: Policy is persisted with default `is_active=True`.
# [/DEF:ValidationPolicyModel:Class]

# [DEF:ValidationPolicySchema:Class]
# @TIER: TRIVIAL
# @SEMANTICS: Pydantic, Schema
# @PURPOSE: API contract for reading and writing Validation Policies.
# @LAYER: API
# @RELATION: DEPENDS_ON -> ValidationPolicyModel
# [/DEF:ValidationPolicySchema:Class]

# [DEF:HealthService:Class]
# @TIER: CRITICAL
# @SEMANTICS: Service, Aggregation
# @PURPOSE: Aggregates dashboard metadata with the latest ValidationRecord to produce health summaries.
# @LAYER: Domain
# @RELATION: CALLS -> SupersetClient.get_dashboards_summary
# @RELATION: DEPENDS_ON -> ValidationRecord
# @PRE: Valid environment_id is provided.
# @POST: Returns an aggregated list of DashboardHealthItems with status, issues, and timestamp.
# @TEST_CONTRACT: Input(environment_id: str) -> List[DashboardHealthItem]
# @TEST_SCENARIO: test_health_aggregation_success -> Returns latest record per dashboard.
# @TEST_FIXTURE: test_health_aggregation_success -> mock_dashboards_and_records
# @TEST_EDGE: test_health_aggregation_no_records -> Returns UNKNOWN status for dashboards without records.
# @TEST_INVARIANT: latest_record_wins -> VERIFIED_BY: [test_health_aggregation_success]
# [/DEF:HealthService:Class]

# [DEF:HealthRouter:Module]
# @TIER: STANDARD
# @SEMANTICS: FastAPI, Route
# @PURPOSE: API endpoints for the Health Center UI.
# @LAYER: API
# @RELATION: CALLS -> HealthService
# @PRE: Request includes valid authentication token.
# @POST: Returns JSON list of dashboard health statuses.
# [/DEF:HealthRouter:Module]

# [DEF:NotificationService:Class]
# @TIER: CRITICAL
# @SEMANTICS: Service, PubSub
# @PURPOSE: Evaluates policies and routes formatted notifications to dynamically resolved owners and explicit channels.
# @LAYER: Domain
# @RELATION: DEPENDS_ON -> ValidationResult
# @RELATION: DEPENDS_ON -> ValidationPolicyModel
# @RELATION: CALLS -> ProfileService (to map Superset owners to local contacts)
# @PRE: Receives a completed ValidationResult and its trigger Policy.
# @POST: Dispatches messages asynchronously via BackgroundTasks to configured providers.
# @TEST_CONTRACT: Input(ValidationResult, Policy) -> List[DispatchedAlert]
# @TEST_SCENARIO: test_owner_routing -> Matches Superset owner 'ivan' to profile Telegram ID and sends.
# @TEST_FIXTURE: test_owner_routing -> mock_profile_with_telegram
# @TEST_EDGE: test_missing_profile_contact -> Skips owner if no valid contact info is found without crashing.
# @TEST_INVARIANT: async_dispatch -> VERIFIED_BY: [test_owner_routing]
# [/DEF:NotificationService:Class]

# [DEF:NotificationProvider:Class]
# @TIER: STANDARD
# @SEMANTICS: Interface, Strategy
# @PURPOSE: Base abstraction for sending formatted alerts to external systems (SMTP, Slack, Telegram).
# @LAYER: Infra
# @PRE: Receives a standardized AlertPayload (text + image links).
# @POST: Delivers the payload to the external system.
# [/DEF:NotificationProvider:Class]

# [DEF:ThrottledSchedulerConfigurator:Module]
# @TIER: CRITICAL
# @SEMANTICS: Scheduler, APScheduler
# @PURPOSE: Reads active ValidationPolicies and generates distributed cron/date triggers within the defined execution window.
# @LAYER: Core
# @RELATION: DEPENDS_ON -> ValidationPolicyModel
# @RELATION: CALLS -> APScheduler
# @PRE: Receives a list of active policies and current time.
# @POST: N tasks are scheduled exactly within [window_start, window_end] with roughly equal intervals.
# @TEST_CONTRACT: Input(List[ValidationPolicy], current_time) -> List[Trigger]
# @TEST_SCENARIO: test_window_distribution -> 60 tasks in 60 mins -> 1 min interval.
# @TEST_FIXTURE: test_window_distribution -> policy_1hr_60tasks
# @TEST_EDGE: test_window_too_small -> 100 tasks in 1 min -> Falls back to minimum safe interval or logs warning.
# @TEST_INVARIANT: distribution_bounds -> VERIFIED_BY: [test_window_distribution, test_window_too_small]
# [/DEF:ThrottledSchedulerConfigurator:Module]

## Frontend Contracts

# [DEF:HealthMatrix:Component]
# @TIER: STANDARD
# @SEMANTICS: Svelte, UI
# @PURPOSE: Displays traffic light summary cards (Pass, Warn, Fail).
# @LAYER: UI
# @RELATION: READS_FROM -> Health API Response
# @PRE: Receives array of dashboard health data.
# @POST: Renders three numeric summary cards with distinct colors.
# @UX_STATE: Loading -> Skeleton cards.
# @UX_STATE: Idle -> Distinct colored counts.
# [/DEF:HealthMatrix:Component]

# [DEF:HealthCenterPage:Component]
# @TIER: CRITICAL
# @SEMANTICS: SvelteKit, Route
# @PURPOSE: Main monitoring view for dashboard validation health.
# @LAYER: UI
# @RELATION: CALLS -> requestApi(/api/dashboards/health)
# @RELATION: BINDS_TO -> HealthMatrix
# @PRE: User has permission to view dashboards.
# @POST: Renders Environment selector, Health Matrix, and detailed data table.
# @UX_STATE: Loading -> Page skeleton.
# @UX_STATE: Error -> Toast notification and empty state.
# @UX_STATE: Success -> Matrix and populated table.
# @UX_TEST: FilterClick -> {click: "Fail only", expected: table shows only RED rows}
# [/DEF:HealthCenterPage:Component]

# [DEF:AutomationPoliciesPage:Component]
# @TIER: STANDARD
# @SEMANTICS: SvelteKit, Route
# @PURPOSE: Settings view to create and manage validation policies.
# @LAYER: UI
# @RELATION: CALLS -> requestApi(/api/settings/automation/policies)
# @PRE: User is Admin.
# @POST: Renders list of policies and 'Create Rule' modal.
# @UX_STATE: Creating -> Modal is open with form.
# @UX_FEEDBACK: SaveSuccess -> Toast "Policy scheduled".
# [/DEF:AutomationPoliciesPage:Component]

# [DEF:SidebarHealthBadge:Store]
# @TIER: STANDARD
# @SEMANTICS: Svelte Store
# @PURPOSE: Derived or fetched state to show `[🔴 N]` badge on the sidebar.
# @LAYER: UI-State
# @RELATION: DEPENDS_ON -> ActivityStore or specific Health poll
# @PRE: User is logged in.
# @POST: Provides integer count of currently failing dashboards.
# [/DEF:SidebarHealthBadge:Store]