# 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.