# Data Model: Dashboard Health Windows

## Entities

### `ValidationPolicy` (New)

**Layer**: Domain (Backend DB)
**Purpose**: Defines a scheduled rule for validating a group of dashboards within an execution window.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID (PK) | Unique policy identifier |
| `name` | String | Human-readable name for the policy (e.g., "Nightly Critical Prod") |
| `environment_id` | String | Foreign Key to configured Superset environment |
| `is_active` | Boolean | Whether the policy is currently enabled (default: true) |
| `dashboard_ids` | JSON | Array of dashboard string identifiers/slugs targeted by this policy |
| `schedule_days` | JSON | Array of integers representing days of week (0=Mon, 6=Sun) |
| `window_start` | Time | Start time of the execution window (e.g., 01:00) |
| `window_end` | Time | End time of the execution window (e.g., 05:00) |
| `notify_owners` | Boolean | Whether to route alerts dynamically based on Superset owners |
| `custom_channels` | JSON | List of external channels (e.g., `[{"type": "slack", "target": "#alerts"}]`) |
| `alert_condition` | Enum | Trigger condition: `FAIL_ONLY`, `WARN_AND_FAIL`, `ALWAYS` |
| `created_at` | DateTime | Audit timestamp |
| `updated_at` | DateTime | Audit timestamp |

**Relationships**:
*   Targets multiple Dashboards (implied via JSON array of IDs).

### `NotificationConfig` (New)

**Layer**: Domain (Backend DB - `AppConfigRecord` or standalone)
**Purpose**: Global settings for external notification providers (configured by Admins).

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID (PK) | Unique provider config identifier |
| `type` | Enum | Provider type: `SMTP`, `SLACK`, `TELEGRAM` |
| `name` | String | Display name for the config |
| `credentials` | JSON | Encrypted connection details (Host, Token, Password) |
| `is_active` | Boolean | Whether the provider is enabled |

### `UserDashboardPreference` (Extended)

**Layer**: Domain (Backend DB)
**Purpose**: Extended to hold user contact details for smart routing.

| Field | Type | Description |
|-------|------|-------------|
| ... existing ... | | |
| `telegram_id` | String | User's Telegram Chat ID for direct messages |
| `email_address` | String | Override email address for direct notifications |
| `notify_on_fail` | Boolean | Opt-out toggle for automated owner alerts |

### `ValidationRecord` (Updated/Extended)

**Layer**: Domain (Backend DB)
**Purpose**: Represents the outcome of a single dashboard validation task.

*Note: This entity likely already exists partially; this defines the required shape for this feature.*

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID (PK) | Unique record identifier |
| `task_id` | UUID (FK) | Reference to the underlying execution task |
| `dashboard_id` | String (Index) | Identifier of the dashboard checked |
| `environment_id` | String (Index) | Environment where the dashboard lives |
| `status` | Enum | Validation status: `PASS`, `WARN`, `FAIL`, `UNKNOWN` |
| `issues` | JSON | Array of structured issue tags/types found (e.g., `["SQL_ERROR", "TIMEOUT"]`) |
| `llm_summary` | Text | Human-readable explanation of the findings from the LLM |
| `screenshot_path` | String (Optional)| Path to the visual artifact in storage |
| `validated_at` | DateTime | Timestamp of the check |

**Relationships**:
*   `task_id` points to `TaskRecord`.

## API Contracts

### `DashboardItem` (Extension)

The existing `DashboardItem` schema returned by `GET /api/dashboards` will be extended to support the Health Center view.

```json
// Extended fields added to existing response
{
  "validation_status": "PASS | WARN | FAIL | UNKNOWN",
  "validation_issues": ["Broken Chart", "Timeout"],
  "last_validation_time": "2026-03-10T02:15:00Z",
  "last_validation_task_id": "uuid-string"
}
```

### Validation Policy Endpoints

#### `GET /api/settings/automation/policies`
Returns a list of all validation policies.

#### `POST /api/settings/automation/policies`
Creates a new validation policy.

**Request Body**:
```json
{
  "name": "Nightly Check",
  "environment_id": "ss-prod",
  "dashboard_ids": ["123", "456"],
  "schedule_days": [0, 1, 2, 3, 4],
  "window_start": "01:00",
  "window_end": "05:00",
  "notify_owners": true,
  "custom_channels": [
    {"type": "slack", "target": "#data-team"}
  ],
  "alert_condition": "FAIL_ONLY"
}
```

#### Global Notification Settings
- `GET /api/settings/notifications/providers`
- `POST /api/settings/notifications/providers`
- `PUT /api/settings/notifications/providers/{id}`

#### `PUT /api/settings/automation/policies/{policy_id}`
Updates an existing policy.

#### `DELETE /api/settings/automation/policies/{policy_id}`
Deletes a policy.

### AI Assistant Output

The existing Assistant endpoints will need to return deep links to the new Health Center and detailed reports.

```json
// Example Action returned by Assistant
{
  "action_type": "NAVIGATE",
  "url": "/dashboards/health?filter=fail",
  "label": "View Failed Dashboards"
}