138 lines
5.0 KiB
Markdown
138 lines
5.0 KiB
Markdown
# 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"
|
|
} |