141 lines
6.1 KiB
Markdown
141 lines
6.1 KiB
Markdown
# 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]
|