ss-tools/specs/026-dashboard-health-windows/tasks.md

# Implementation Tasks: Dashboard Health Windows

**Feature Branch**: `026-dashboard-health-windows`
**Documentation**: [plan.md](./plan.md) | [spec.md](./spec.md) | [ux_reference.md](./ux_reference.md) | [data-model.md](./data-model.md) | [contracts/modules.md](./contracts/modules.md)

## Dependencies & Execution Order

1.  **Phase 1 & 2**: Setup and Foundation (DB changes, extending scheduler). Blocks all user stories.
2.  **Phase 3**: User Story 1 (Policies). Needs Phase 2.
3.  **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.
4.  **Phase 5**: User Story 3 (Quick Nav). Depends on Phase 4 Health Center backend API.
5.  **Phase 6**: User Story 4 (Smart Notifications). Depends on Phase 2 (Profile schema) and Phase 3 (Policies).
6.  **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:
1.  First, we establish the database schema for policies, profiles, and extended validation records.
2.  Then, we build the "Execution Window" logic in the scheduler (`[US1]`).
3.  Next, we build the Health Center projection API and UI (`[US2]`), giving visibility into the tasks.
4.  We weave the health data into the global app shell (Sidebar, Assistant) (`[US3]`).
5.  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.

- [x] T001 Scaffold `health.py` router in `backend/src/api/routes/health.py`
- [x] T002 Scaffold `health_service.py` in `backend/src/services/health_service.py`
- [x] T003 Scaffold `HealthMatrix.svelte` component in `frontend/src/lib/components/health/HealthMatrix.svelte`
- [x] T004 Scaffold `PolicyForm.svelte` component in `frontend/src/lib/components/health/PolicyForm.svelte`
- [x] T005 Create empty `+page.svelte` for Health Center in `frontend/src/routes/dashboards/health/+page.svelte`
- [x] 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.

- [x] T007 [P] Create `ValidationPolicy` model and update `ValidationRecord` model with new fields in `backend/src/models/llm.py`
- [x] T008 [P] Add `telegram_id`, `email_address`, and `notify_on_fail` fields to `UserDashboardPreference` in `backend/src/models/profile.py`
- [x] T009 [P] Create `NotificationConfig` model for global provider settings in `backend/src/models/config.py` (or as a JSON block in `AppConfigRecord`)
- [x] T010 Generate and apply Alembic migration for all DB changes in `backend/alembic/versions/`
- [x] 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.

- [x] T012 [P] [US1] Create Pydantic schemas for `ValidationPolicy` (Create/Update/Response) in `backend/src/schemas/settings.py` (or new schema file)
- [x] T013 [US1] Implement CRUD endpoints for validation policies in `backend/src/api/routes/settings.py` (or new automation router)
- [x] 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)
- [x] T015 [P] [US1] Create `PolicyForm` component for editing/creating policies in `frontend/src/lib/components/health/PolicyForm.svelte`
- [x] T016 [US1] Implement Automation Policies page list and modal management in `frontend/src/routes/settings/automation/+page.svelte`
- [x] T017 [US1] Add "Automation" tab to the global settings navigation in `frontend/src/routes/settings/+page.svelte`
- [x] 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.

- [x] 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`
- [x] T020 [US2] Implement `GET /api/dashboards/health` endpoint in `backend/src/api/routes/health.py` (or extend `dashboards.py`)
- [x] T021 [P] [US2] Implement `HealthMatrix` UI component (Pass/Warn/Fail traffic lights) in `frontend/src/lib/components/health/HealthMatrix.svelte`
- [x] T022 [US2] Implement Health Center page fetching data and rendering the matrix and data table in `frontend/src/routes/dashboards/health/+page.svelte`
- [x] T023 [US2] Link "View Report" button in Health Center table to the detailed LLM report route `frontend/src/routes/reports/llm/[taskId]/+page.svelte`
- [x] T024 [US2] Verify implementation matches `ux_reference.md` (Happy Path & Errors) for the Health Center view.

## Phase 5: User Story 3 - Quick Navigation and Integrations (P3)

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.

- [x] T025 [US3] Create `SidebarHealthBadge` store (fetches or derives failing count) in `frontend/src/lib/stores/health.js` (or extend `activity.js`)
- [x] 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`
- [x] 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.
- [x] 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.

- [x] T029 [P] [US4] Update `frontend/src/routes/profile/+page.svelte` to include Telegram ID and email override inputs.
- [x] T030 [P] [US4] Implement `NotificationProvider` abstractions (SMTP, Slack, Telegram) in `backend/src/services/notifications/providers.py`
- [x] 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`
- [x] T032 [US4] Wire `NotificationService.dispatch_report` into the end of `DashboardValidationPlugin.execute` in `backend/src/plugins/llm_analysis/plugin.py`
- [x] T033 [US4] Implement Global Settings UI for configuring Notification Providers in `frontend/src/routes/settings/notifications/+page.svelte`
- [x] 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.

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

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

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