6.0 KiB
6.0 KiB
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]
[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]
[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]
[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]
[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]
[DEF:NotificationProvider:Interface]
@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]
[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]
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]
[DEF:HealthCenterPage:Page]
@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]
[DEF:AutomationPoliciesPage:Page]
@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]
[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]