ss-tools/specs/008-migration-ui-improvements/spec.md

Feature Specification: Migration UI Improvements

Feature Branch: 008-migration-ui-improvements
Created: 2025-12-27
Status: Draft
Input: User description: "я хочу доработать интерфейс миграции: 1. Необходимо выводить список последних (и текущую) задач миграции с их статусами и возможностью посмотреть лог миграции 2. Необходимо корректно отрабатывать ошибки миграции БД, например такую [Backend] 2025-12-27 09:47:12,230 - ERROR - [import_dashboard][Failure] First import attempt failed: [API_FAILURE] API error during upload: {"errors": [{"message": "Error importing dashboard: databases/PostgreSQL.yaml: {'_schema': ['Must provide a password for the database']}", "error_type": "GENERIC_COMMAND_ERROR", "level": "warning", "extra": {"databases/PostgreSQL.yaml": {"_schema": ["Must provide a password for the database"]}, "issue_codes": [{"code": 1010, "message": "Issue 1010 - Superset encountered an error while running a command."}]}}]} | Context: {'type': 'api_call'} ... Здесь видно, что можно предложить пользователю ввести пароль от БД"

User Scenarios & Testing (mandatory)

User Story 1 - Task History and Status (Priority: P1)

As a user, I want to see a list of my recent and currently running migration tasks so that I can track progress and review past results.

Why this priority: Essential for visibility into background processes and troubleshooting.

Independent Test: Can be fully tested by starting a migration and verifying it appears in a "Recent Tasks" list with its current status.

Acceptance Scenarios:

1. Given the Migration Dashboard, When I open the page, Then I see a list of recent migration tasks with their status (Pending, Running, Success, Failed).
2. Given a running task, When the task updates its status on the backend, Then the UI reflects the status change in real-time or upon refresh.

---

User Story 2 - Task Log Inspection (Priority: P2)

As a user, I want to view the detailed logs of any migration task so that I can understand exactly what happened or why it failed.

Why this priority: Critical for debugging failures and confirming success details.

Independent Test: Can be tested by clicking a "View Logs" button for a task and seeing a modal or panel with the task's log entries.

Acceptance Scenarios:

1. Given a migration task in the history list, When I click "View Logs", Then a detailed log view opens showing timestamped messages from that task.

---

User Story 3 - Interactive Database Password Resolution (Priority: P1)

As a user, I want the system to detect when a migration fails due to a missing database password and allow me to provide it interactively.

Why this priority: Prevents migration blocks due to Superset's security requirements (passwords are not exported).

Independent Test: Can be tested by triggering a migration that requires a DB password and verifying the UI prompts for the password instead of just failing.

Acceptance Scenarios:

1. Given a migration task that encounters a "Must provide a password for the database" error, When the error is detected, Then the task status changes to "Awaiting Input" and the UI prompts the user to enter the password for the specific database.
2. Given a password prompt, When I enter the password and submit, Then the migration resumes using the provided password.

---

Edge Cases

• Multiple Missing Passwords: How does the system handle multiple databases in one migration needing passwords? (Assumption: Prompt sequentially or as a list).
• Invalid Password Provided: What happens if the user provides an incorrect password? (Assumption: System should detect the new error and prompt again or fail gracefully).
• Task Manager Restart: How are tasks persisted across backend restarts? (Assumption: Currently tasks are in-memory; persistence might be needed for "Recent Tasks" to be truly useful).

Clarifications

Session 2025-12-27

• Q: What is the expected data retention policy for migration task history? Should the system keep all tasks indefinitely, or is there a retention limit (e.g., last 50 tasks, last 30 days)? → A: Configurable retention period (default: last 50 tasks or 30 days, configurable via settings)
• Q: How should the system handle multiple databases requiring passwords in a single migration? Should it prompt for all missing passwords at once, or sequentially as each one is encountered? → A: Prompt for all missing passwords at once in a single form
• Q: What should happen when a user provides an incorrect database password? Should the system retry the same password, prompt again with an error message, or fail the migration entirely? → A: Prompt again with an error message explaining the password was incorrect
• Q: How should task persistence be handled across backend restarts? Should tasks be persisted to a database, kept in-memory only, or use a hybrid approach? → A: Hybrid approach: persist only tasks that need user input
• Q: What performance requirements should the task history API meet? Should it support pagination, filtering, or have specific response time targets? → A: Basic pagination only (limit/offset)

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST provide an API endpoint to retrieve the list of all tasks from TaskManager.
• FR-002: System MUST provide an API endpoint to retrieve full logs for a specific task ID.
• FR-003: Migration Dashboard MUST display a list of recent tasks including ID, start time, status, and a "View Logs" action.
• FR-004: MigrationPlugin MUST detect specific Superset API errors related to missing database passwords (e.g., matching the UNPROCESSABLE ENTITY 422 error with specific JSON body).
• FR-005: System MUST support a task state "AWAITING_INPUT" (extending AWAITING_MAPPING) specifically for interactive password entry.
• FR-006: UI MUST display an interactive prompt when a task enters "AWAITING_INPUT" state due to missing DB password.
• FR-007: System MUST allow resuming a task with provided sensitive information (passwords) without persisting them permanently if not required.

Non-Functional Requirements

• NFR-001: System MUST implement configurable retention policy for migration task history with default values of last 50 tasks or 30 days, configurable via settings.

Key Entities

• Task: Represents a migration execution (Existing: backend/src/core/task_manager.py:Task). Needs to ensure logs are accessible.
• MigrationLog: A single entry in a task's log (Existing: LogEntry).
• DatabasePasswordRequest: A specific type of resolution request sent to the UI.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can view the status of their last 10 migration tasks directly on the migration page.
• SC-002: Users can access the full log of any recent task in less than 2 clicks.
• SC-003: 100% of "Missing Password" errors are caught and presented as interactive prompts rather than fatal migration failures.
• SC-004: Users can successfully resume a "blocked" migration by providing the required password through the UI.