Implementation Tasks: Dashboard Health Windows

Feature Branch: 026-dashboard-health-windows Documentation: plan.md | spec.md | ux_reference.md | data-model.md | contracts/modules.md

Dependencies & Execution Order

Phase 1 & 2: Setup and Foundation (DB changes, extending scheduler). Blocks all user stories.
Phase 3: User Story 1 (Policies). Needs Phase 2.
Phase 4: User Story 2 (Health Center). Can be built in parallel with Phase 3 on the frontend, but backend depends on data model changes in Phase 2.
Phase 5: User Story 3 (Quick Nav). Depends on Phase 4 Health Center backend API.
Phase 6: User Story 4 (Smart Notifications). Depends on Phase 2 (Profile schema) and Phase 3 (Policies).
Phase 7: Polish. Depends on all previous phases.

Parallel Execution Opportunities:

[US1] (Policies UI) can be built in parallel with [US2] (Health Matrix UI) and [US4] (Notification settings UI).
Backend and frontend tasks within a user story can generally be developed in parallel up to integration.

Implementation Strategy

We will deliver this feature incrementally:

First, we establish the database schema for policies, profiles, and extended validation records.
Then, we build the "Execution Window" logic in the scheduler ([US1]).
Next, we build the Health Center projection API and UI ([US2]), giving visibility into the tasks.
We weave the health data into the global app shell (Sidebar, Assistant) ([US3]).
Finally, we implement the NotificationService and integrate it into the task execution pipeline to shift to a "push" model ([US4]).

Phase 1: Setup

Goal: Initialize the project structure for the new feature modules.

T001 Scaffold health.py router in backend/src/api/routes/health.py
T002 Scaffold health_service.py in backend/src/services/health_service.py
T003 Scaffold HealthMatrix.svelte component in frontend/src/lib/components/health/HealthMatrix.svelte
T004 Scaffold PolicyForm.svelte component in frontend/src/lib/components/health/PolicyForm.svelte
T005 Create empty +page.svelte for Health Center in frontend/src/routes/dashboards/health/+page.svelte
T006 Create empty +page.svelte for Automation Policies in frontend/src/routes/settings/automation/+page.svelte

Phase 2: Foundational

Goal: Implement the core data model and generic backend updates required by all stories.

T007 [P] Create ValidationPolicy model and update ValidationRecord model with new fields in backend/src/models/llm.py
T008 [P] Add telegram_id, email_address, and notify_on_fail fields to UserDashboardPreference in backend/src/models/profile.py
T009 [P] Create NotificationConfig model for global provider settings in backend/src/models/config.py (or as a JSON block in AppConfigRecord)
T010 Generate and apply Alembic migration for all DB changes in backend/alembic/versions/
T011 Update TaskReport schema to support the extended ValidationRecord shape in backend/src/models/report.py

Phase 3: User Story 1 - Create Validation Policy with Execution Window (P1)

Goal: Allow users to define validation policies with execution windows and have the backend distribute tasks within that window.

Independent Test: Can be tested by creating a policy with a 1-hour window for 60 dashboards and verifying that the system schedules 60 distinct validations spread roughly 1 minute apart.

T012 [P] [US1] Create Pydantic schemas for ValidationPolicy (Create/Update/Response) in backend/src/schemas/settings.py (or new schema file)
T013 [US1] Implement CRUD endpoints for validation policies in backend/src/api/routes/settings.py (or new automation router)
T014 [US1] Implement ThrottledSchedulerConfigurator logic. (CRITICAL: PRE: active policies + time, POST: N tasks scheduled evenly. TESTS: window distribution, too small window fallback) in backend/src/core/scheduler.py (or new core module)
T015 [P] [US1] Create PolicyForm component for editing/creating policies in frontend/src/lib/components/health/PolicyForm.svelte
T016 [US1] Implement Automation Policies page list and modal management in frontend/src/routes/settings/automation/+page.svelte
T017 [US1] Add "Automation" tab to the global settings navigation in frontend/src/routes/settings/+page.svelte
T018 [US1] Verify implementation matches ux_reference.md (Happy Path & Errors) for the Automation Settings view.

Phase 4: User Story 2 - Dashboard Health Center Monitoring (P2)

Goal: Provide a traffic-light summary view of the latest validation status for all dashboards.

Independent Test: Can be tested by running several validation tasks (some pass, some fail) and viewing the Health Center to ensure it correctly aggregates and displays only the latest status for each unique dashboard.

T019 [P] [US2] Implement HealthService.get_health_summary. (CRITICAL: PRE: environment_id, POST: aggregated List[DashboardHealthItem]. TESTS: aggregation success, no-records fallback) in backend/src/services/health_service.py
T020 [US2] Implement GET /api/dashboards/health endpoint in backend/src/api/routes/health.py (or extend dashboards.py)
T021 [P] [US2] Implement HealthMatrix UI component (Pass/Warn/Fail traffic lights) in frontend/src/lib/components/health/HealthMatrix.svelte
T022 [US2] Implement Health Center page fetching data and rendering the matrix and data table in frontend/src/routes/dashboards/health/+page.svelte
T023 [US2] Link "View Report" button in Health Center table to the detailed LLM report route frontend/src/routes/reports/llm/[taskId]/+page.svelte
T024 [US2] Verify implementation matches ux_reference.md (Happy Path & Errors) for the Health Center view.

Goal: Integrate the failing dashboard counts into the sidebar and the AI Assistant.

Independent Test: Can be tested by having failing validations in the database and checking that the sidebar navigation displays a red badge with the correct count, and querying the assistant returns accurate results.

T025 [US3] Create SidebarHealthBadge store (fetches or derives failing count) in frontend/src/lib/stores/health.js (or extend activity.js)
T026 [US3] Update Sidebar component to display the red [🔴 N] badge next to the Dashboards menu item in frontend/src/lib/components/layout/Sidebar.svelte
T027 [US3] Update backend/src/api/routes/assistant.py (or the underlying tool catalog) to resolve queries about "failing dashboards" by querying the HealthService and returning deep links.
T028 [US3] Verify implementation matches ux_reference.md (Happy Path & Errors) for Sidebar and Assistant integration.

Phase 6: User Story 4 - Smart Notifications Routing (P2)

Goal: Implement the backend routing logic and external providers to send push notifications.

Independent Test: Can be tested by configuring a user profile with a Telegram ID, running a validation task that fails for a dashboard owned by that user in Superset, and verifying the NotificationService dispatches a payload to the Telegram provider.

T029 [P] [US4] Update frontend/src/routes/profile/+page.svelte to include Telegram ID and email override inputs.
T030 [P] [US4] Implement NotificationProvider abstractions (SMTP, Slack, Telegram) in backend/src/services/notifications/providers.py
T031 [US4] Implement NotificationService for routing logic. (CRITICAL: PRE: ValidationResult, POST: Dispatches to providers via BackgroundTasks. TESTS: owner routing, missing profile resilience) in backend/src/services/notifications/service.py
T032 [US4] Wire NotificationService.dispatch_report into the end of DashboardValidationPlugin.execute in backend/src/plugins/llm_analysis/plugin.py
T033 [US4] Implement Global Settings UI for configuring Notification Providers in frontend/src/routes/settings/notifications/+page.svelte
T034 [US4] Verify implementation matches ux_reference.md (Happy Path & Errors) for Notification payloads and UI.

Phase 7: Polish & Cross-Cutting

Goal: Finalize styling, error handling, and end-to-end flow.

T035 Ensure consistent Tailwind styling and dark mode support across HealthMatrix and PolicyForm.
T036 Add comprehensive error toasts for policy creation failures (e.g., overlapping windows, invalid IDs).
T037 Write/update unit tests for ThrottledSchedulerConfigurator bounds handling.
T038 Write/update unit tests for HealthService latest-record aggregation logic.

Post-Review Fix Batch (2026-03-10)

R001 Persist task_id and environment_id in ValidationRecord creation path (llm_analysis/plugin.py).
R002 Align policy channel schema contract: custom_channels migrated to structured objects {type,target} in settings schemas.
R003 Tighten health status regex to strict grouped anchors ^(PASS|WARN|FAIL|UNKNOWN)$.
R004 Resolve weekday convention drift to 0=Sunday ... 6=Saturday consistently across backend schema description and policy form UI.
R005 Add regression tests for schema contracts and plugin persistence context fields.
R006 Make health report deletion resilient to linked task/log cleanup failures and cover the fallback with unit tests.
R007 Align Health Center delete action with latest-record aggregation by deleting all validation reports for the selected dashboard/environment scope.

9.5 KiB Raw Blame History