TaskManager refactor
This commit is contained in:
99
specs/008-migration-ui-improvements/spec.md
Normal file
99
specs/008-migration-ui-improvements/spec.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user