# Feature Specification: Backup Scheduler & Unified Task UI

**Feature Branch**: `009-backup-scheduler`
**Created**: 2025-12-30
**Status**: Draft
**Input**: User description: "Я хочу доработать механизм бекапа. Он должен иметь возможность работать по расписанию, задания и их статус должны использовать TaskManager и быть доступны в общем логе. Я думаю нужно вынести все задачи в отдельную вкладку - миграции, бэкапов и прочих задач которые мы в будущем добавим."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Scheduled Backups (Priority: P1)

As an Administrator, I want to configure automatic backup schedules for my Superset environments so that my data is preserved regularly without manual intervention.

**Why this priority**: Automation is the core request. It ensures data safety and reduces manual toil.

**Independent Test**: Configure a schedule (e.g., every minute for testing), wait, and verify a backup task is created and executed automatically.

**Acceptance Scenarios**:

1. **Given** an environment configuration, **When** I enable scheduled backups with a specific interval (e.g., daily), **Then** the system automatically triggers a backup task at the specified time.
2. **Given** a scheduled backup runs, **When** it completes, **Then** a new backup archive is present in the storage and a success log is recorded.

---

### User Story 2 - Unified Task Management UI (Priority: P1)

As an Administrator, I want a dedicated "Tasks" tab where I can see and manage all background operations (backups, migrations) in one place.

**Why this priority**: Centralizes visibility and control, improving usability as the number of background tasks grows.

**Independent Test**: Navigate to the new "Tasks" tab and verify it lists both manual and scheduled tasks with their current status.

**Acceptance Scenarios**:

1. **Given** the application is open, **When** I click the "Tasks" tab, **Then** I see a list of recent tasks including their type (Backup, Migration), status, and timestamp.
2. **Given** a running task, **When** I view the Tasks tab, **Then** I see the task status update in real-time (or near real-time).

---

### User Story 3 - Manual Backup Trigger (Priority: P2)

As an Administrator, I want to manually trigger a backup from the Tasks UI immediately, for example, before a major change.

**Why this priority**: Ad-hoc backups are necessary for operational safety before maintenance.

**Independent Test**: Click "Run Backup" in the UI and verify a new task starts immediately.

**Acceptance Scenarios**:

1. **Given** the Tasks tab is open, **When** I select an environment and click "Run Backup", **Then** a new backup task appears in the list with "Running" status.

---

### User Story 4 - Task History & Logs (Priority: P2)

As an Administrator, I want to view the detailed logs of any executed task to troubleshoot failures or verify success.

**Why this priority**: Essential for debugging and auditability.

**Independent Test**: Click on a completed task and verify the log output is displayed.

**Acceptance Scenarios**:

1. **Given** a list of tasks, **When** I click on a "Failed" task, **Then** I can see the error logs explaining why it failed.
2. **Given** a "Success" task, **When** I view logs, **Then** I see the execution steps confirmation.

### Edge Cases

- **Concurrent Backups**: What happens if a scheduled backup triggers while a manual backup is already running for the same environment? (System should likely queue or skip).
- **Storage Full**: How does the system handle backup failures due to insufficient disk space? (Should fail gracefully and log error).
- **Superset Offline**: What happens if the Superset environment is unreachable when a backup is triggered? (Task fails with connection error).

### Assumptions

- The backend server is running continuously to process scheduled tasks.
- Users have configured valid credentials for Superset environments.
- There is sufficient storage space for backup archives.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: The system MUST allow users to configure a backup schedule using **Cron expressions** for each defined Superset environment via the **Settings** page.
- **FR-002**: The system MUST persist schedule configurations nested within the Environment configuration in `config.json`.
- **FR-003**: The system MUST include a `SchedulerService` running in a background thread that triggers backup tasks via the `TaskManager`.
- **FR-004**: The system MUST provide a dedicated "Tasks" page in the frontend.
- **FR-005**: The "Tasks" page MUST display a unified list of all `TaskManager` jobs, including Migrations and Backups.
- **FR-006**: The "Tasks" page MUST allow users to filter tasks by status (Running, Success, Failed) and type.
- **FR-007**: The system MUST allow users to manually trigger a backup for a specific environment from the "Tasks" page.
- **FR-008**: All backup operations (scheduled or manual) MUST be executed as `TaskManager` tasks and generate standard logs.
- **FR-009**: The system MUST retain a history of task executions in a dedicated SQLite database (`tasks.db`) for long-term review.
- **FR-010**: The system MUST automatically clean up task history older than 30 days to prevent unbounded database growth.

### Key Entities

- **Task**: Represents a unit of work (Backup, Migration) managed by TaskManager. Attributes: ID, Type, Status, StartedAt, FinishedAt, Logs.
- **Schedule**: Configuration for when to run a task. Attributes: EnvironmentID, Frequency, NextRunTime, Enabled.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: Users can configure a backup schedule that persists and triggers automatically within 1 minute of the target time.
- **SC-002**: The "Tasks" UI displays the status of running tasks with a latency of no more than 5 seconds.
- **SC-003**: 100% of triggered backups (manual or scheduled) are recorded in the TaskManager history.
- **SC-004**: Users can access logs for any task executed in the last 7 days (or configured retention period).

## Clarifications

### Session 2025-12-30
- Q: Where should the backup schedule configuration UI be located? → A: In the **Settings** tab, inside each Environment's edit form.
- Q: How should schedule configurations be persisted? → A: Add a `Schedule` model in `config_models.py` and nest it under `Environment`.
- Q: What format should be used for defining schedule frequency? → A: Cron-style strings (e.g., "0 0 * * *").
- Q: How should the scheduling mechanism be implemented? → A: Create a dedicated `SchedulerService` in `backend/src/core/scheduler.py` that runs in a background thread.
- Q: Where should task history be stored for long-term retention? → A: Add a `tasks.db` SQLite database using SQLAlchemy.