ss-tools/specs/019-superset-ux-redesign/spec.md

Feature Specification: Superset-Style UX Redesign

Feature Branch: 019-superset-ux-redesign
Reference UX: ux_reference.md Created: 2026-02-08
Status: Draft
Input: User description: "Я хочу переработать пользовательский UX полностью, уйдя от карточек дашборда к структуре сходной к Apache Superset. Переход к Resource-Centric модели."

User Scenarios & Testing (mandatory)

User Story 1 - Resource-Centric Navigation (Priority: P1)

As a user, I want to navigate the application through a persistent left sidebar that focuses on resources (Dashboards, Datasets, Storage) rather than tools, so I can manage my data objects more intuitively.

Why this priority: This is the core shift in the application's philosophy. It defines how users find and interact with everything else.

Independent Test: Can be tested by clicking "Dashboards" or "Datasets" in the sidebar and verifying the correct resource hub loads.

Acceptance Scenarios:

1. Given the application has loaded, When I view the left sidebar, Then I see primary resource links: DASHBOARDS, DATASETS, STORAGE.
2. Given I am on any page, When I click "Dashboards", Then I am taken to the Dashboard Hub showing a list of all available dashboards from the selected environment.
3. Given I am on a mobile device, When I view the application, Then the sidebar is hidden by default and accessible via hamburger menu.

---

User Story 2 - Global Task Drawer & Activity Monitoring (Priority: P1)

As a user, I want to see a global activity indicator and a slide-out Task Drawer, so I can monitor running tasks (migrations, backups) without losing my current context in a resource list.

Why this priority: Context preservation is a key goal of the redesign. Users must be able to trigger an action and see its progress without leaving the page.

Independent Test: Trigger a "Backup" on a dashboard and verify the Task Drawer opens automatically with the log stream.

Acceptance Scenarios:

1. Given a task is running, When I look at the navbar, Then I see an "Activity" indicator with the count of active tasks.
2. Given I click the "Activity" indicator or a status badge in a grid, When the Task Drawer opens, Then I see the real-time log stream for the selected task.
3. Given a task requires input (e.g., password), When the Task Drawer is open, Then the input form is rendered inside the drawer's interactive area.

---

User Story 3 - Dashboard Hub Management (Priority: P2)

As a user, I want a central hub for dashboards where I can see their Git status and trigger actions like Migrate or Backup from a single row, so I don't have to switch between different tools.

Why this priority: Consolidates multiple existing tools (Migration, Git, Backup) into a single resource-focused view.

Independent Test: Navigate to /dashboards, select an environment, and verify the grid displays Title, Slug, Git Status, and Last Task status.

Acceptance Scenarios:

1. Given I am in the Dashboard Hub, When I click the "Actions" menu for a dashboard, Then I see options for Migrate, Backup, and Git Operations.
2. Given a dashboard is linked to Git, When I view the grid, Then I see its current branch and sync status (OK/Diff).
3. Given I click "Migrate", When the deployment modal opens, Then it only asks for the target environment, keeping the source context from the hub.

---

User Story 4 - Dataset Hub & Semantic Mapping (Priority: P2)

As a user, I want a dedicated hub for datasets where I can manage documentation and field mappings, so I can ensure data consistency across environments.

Why this priority: Moves dataset management from a secondary tool to a primary resource.

Independent Test: Navigate to /datasets and verify the list of tables/schemas is displayed with mapping progress.

Acceptance Scenarios:

1. Given I am in the Dataset Hub, When I view a dataset row, Then I see the "Mapped Fields" count (e.g., 15/20).
2. Given I click "Map Columns" in the actions menu, Then the mapping interface opens (replacing the old standalone Mapper page).

---

User Story 5 - Unified Top Navigation Bar (Priority: P1)

As a user, I want a consistent top navigation bar with a global activity indicator, search placeholder, and user menu, so I can always access critical functions regardless of my current location in the app.

Why this priority: The top navbar is the global command center. It must be established early to provide consistent access to activity monitoring and user settings.

Independent Test: Navigate to any page and verify the top bar shows: Logo, Search, Activity indicator, and User menu.

Acceptance Scenarios:

1. Given the application has loaded, When I view the top navigation bar, Then I see (from left to right): Logo/Brand, Global Search (placeholder), Activity indicator with badge count, User avatar/menu.
2. Given I click the User avatar, When the dropdown opens, Then I see options for: Profile, Settings, Logout.
3. Given there are running tasks, When I view the Activity indicator, Then I see a badge with the count of active tasks.
4. Given I click the Activity indicator, When the Task Drawer is not open, Then the Task Drawer slides out showing the list of recent/active tasks.

---

User Story 6 - Consolidated Settings Experience (Priority: P2)

As an administrator, I want all system settings (Environments, Connections, LLM, Logging) consolidated into a single "Settings" section accessible from the sidebar, so I don't have to hunt through multiple pages to configure the system.

Why this priority: Reduces cognitive load by grouping all configuration in one place. Depends on navigation being established.

Independent Test: Navigate to Settings from the sidebar and verify all configuration categories are listed.

Acceptance Scenarios:

1. Given I am logged in as admin, When I click "Settings" in the sidebar, Then I am taken to a Settings overview page with categories: Environments, Connections, LLM Providers, Logging, System.
2. Given I am on the Settings page, When I click "Environments", Then I see the environment management interface (add/edit/delete Superset instances).
3. Given I am on the Settings page, When I click "Connections", Then I see database connection configurations.
4. Given I am a non-admin user, When I view the sidebar, Then the "Settings" section is either hidden or shows only user-preference items (theme, language).

---

Edge Cases

• Deep Navigation: Breadcrumbs should handle long paths by truncating middle segments with an ellipsis.
• Task Interruption: If the drawer is closed while a task is running, the task must continue in the background, and the navbar indicator must reflect its status.
• Permission Changes: If a user's role changes, the sidebar must immediately hide/show restricted sections (like ADMIN) without a full page reload if possible.
• Empty States: Resource hubs must show helpful empty states when no environments are configured or no resources are found.

Requirements (mandatory)

Functional Requirements

Navigation & Layout

• FR-001: System MUST implement a persistent left sidebar with resource-centric categories (DASHBOARDS, DATASETS, STORAGE, ADMIN).
• FR-002: System MUST implement a Global Task Drawer that slides out from the right, capable of displaying log streams and interactive forms.
• FR-003: System MUST provide a top navigation bar containing: Logo/Brand, Global Search (placeholder), Activity indicator, User menu.
• FR-004: System MUST display breadcrumb navigation at the top of the content area for all pages.
• FR-005: System MUST persist sidebar collapse/expand state in local storage.
• FR-006: System MUST highlight the active resource/category in the sidebar.

Resource Hubs

• FR-007: System MUST implement a Dashboard Hub (/dashboards) that aggregates Migration, Git, and Backup actions for individual dashboards.
• FR-008: System MUST implement a Dataset Hub (/datasets) for managing table metadata and field mappings.
• FR-009: System MUST support a "Source Environment" selector at the top of resource hubs to fetch metadata from different Superset instances.

Task Management

• FR-010: System MUST provide a Navbar "Activity" indicator showing the number of active background tasks.
• FR-011: System MUST render interactive task prompts (like PasswordPrompt) inside the Task Drawer instead of global modals.
• FR-012: System MUST allow users to close the Task Drawer while a task continues running in the background.

Settings & Configuration

• FR-013: System MUST consolidate all admin settings into a single "Settings" section with categories: Environments, Connections, LLM Providers, Logging, System.
• FR-014: System MUST hide admin-only settings categories from non-admin users.
• FR-015: System MUST provide user-preference settings (theme, language) accessible to all users.

Key Entities

• Resource (Dashboard/Dataset): The primary object of management, identified by a unique ID/Slug.
• Task: An asynchronous operation (Migration, Backup, Git Sync) associated with a Resource.
• Task Drawer: A global UI component for monitoring and interacting with Tasks.
• Environment: A Superset instance configuration (Source/Target) used to fetch or deploy resources.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can trigger a migration for a specific dashboard in exactly 2 clicks from the Dashboard Hub.
• SC-002: Task Drawer opens and starts streaming logs within 200ms of a status badge click.
• SC-003: 100% of existing "Tool" functionality (Migration, Git, Mapper) is accessible via the new Resource Hubs.
• SC-004: Users can monitor a running task while simultaneously browsing other resources in the grid.
• SC-005: Zero "blocking" modals used for task-related inputs; all moved to the Task Drawer.

Assumptions

• The backend task_manager already supports task IDs and log streaming (confirmed by existing code).
• superset_client can fetch dashboard/dataset lists efficiently.
• Users prefer a "Resource-First" workflow similar to modern data platforms.

Dependencies

• backend/src/core/task_manager: For task state and log persistence.
• frontend/src/components/TaskLogViewer: To be integrated into the Task Drawer.
• frontend/src/lib/stores/tasks.js: New store required to track resource-to-task mapping.

Out of Scope

• Redesigning the actual Superset dashboard viewing experience (we manage metadata, not the iframe).
• Real-time collaboration features (multiple users editing the same mapping).
• Mobile-first optimization (responsive is required, but desktop is the primary target).