ss-tools/specs/009-backup-scheduler/spec.md

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.