ss-tools/specs/007-migration-dashboard-grid/spec.md

Feature Specification: Migration Plugin Dashboard Grid

Feature Branch: 007-migration-dashboard-grid Created: 2025-12-27 Status: Draft Input: User description: "Я хочу доработать плагин миграции. Выбор дашбордов должен осуществляться из списка-грида, с возможностью его фильтровать по наименованию. В гриде должны быть поля наименования дашборда, дата последнего изменения дашборда, плюс статус - опубликован или черновик"

Clarifications

Session 2025-12-27

• Q: How should the grid handle data loading and filtering to ensure performance and usability? → A: Client-side (Fetch all, filter locally).
• Q: Should the grid include a "Select All" checkbox in the header for bulk operations? → A: Yes, include "Select All".
• Q: How should the grid handle large lists of dashboards (e.g., >50)? → A: Pagination (e.g., 20 per page).
• Q: Does the "Select All" checkbox select only the currently visible page of dashboards, or all dashboards that match the current filter? → A: All matching filter (Selects all filtered results, not just the visible page).
• Q: What should happen if the user changes the filter while some items are already selected? → A: Preserve selection (Selected items remain selected even if hidden by new filter).
• Q: What should be the default sort order when the dashboard grid first loads? → A: Last Modified Date (Newest first).
• Q: Should the grid include an "Owners" column to help distinguish dashboards with the same name? → A: Yes, include Owners.
• Q: How should the "Owners" column display multiple owners? → A: Show first owner + count (e.g., "admin + 2") with tooltip.
• Q: How should the "Status" (Draft/Published) be visually represented in the grid? → A: Colored Badges/Chips.
• Q: Should the grid include a "Preview" action (e.g., link to open the dashboard in Superset)? → A: Yes, open in new tab.

User Scenarios & Testing (mandatory)

User Story 1 - Advanced Dashboard Selection (Priority: P1)

As a migration engineer, I want to select dashboards from a detailed grid view that includes status and modification dates, so that I can easily distinguish between draft/published versions and identify the most recent changes before migrating.

Why this priority: Current selection mechanisms (likely simple dropdowns or lists) lack critical context (status, freshness), making it error-prone to select the right assets for migration.

Independent Test: Can be tested by connecting to a Superset instance with known dashboards (some drafts, some published) and verifying the grid correctly displays their metadata and allows filtering/selection.

Acceptance Scenarios:

1. Given I have selected a source environment in the migration plugin, When the dashboard list loads, Then I see a grid view displaying "Dashboard Name", "Last Modified", and "Status" columns.
2. Given the dashboard grid is displayed, When I type "Sales" into the filter input, Then the grid updates to show only dashboards containing "Sales" in their name.
3. Given a dashboard is in "Draft" state in Superset, When it appears in the grid, Then the Status column clearly indicates "Draft" (vs "Published").
4. Given I want to migrate multiple dashboards, When I check the boxes next to several rows, Then they are added to the selection for the migration job.
5. Given the grid is populated, When I click the "Select All" checkbox in the header, Then all visible dashboards are selected.

---

Edge Cases

• Empty Environment: What happens if the source environment has no dashboards? System should display a "No dashboards found" message in the grid area.
• Missing Metadata: What if the Superset API returns null for changed_on or published? System should display "N/A" or a default value (e.g., "Unknown") rather than crashing.
• Large Dataset: How does the grid handle 1000+ dashboards? The grid MUST use pagination (default 20 items per page) to manage display density.

Requirements (mandatory)

Functional Requirements

• FR-001: The system MUST fetch extended metadata for dashboards from the Superset API, specifically: Title, Last Modified Date (changed_on), and Published Status (published).
• FR-002: The Migration Plugin UI MUST display a data grid component to list these dashboards.
• FR-003: The grid MUST include sortable columns for:
  • Name (Dashboard Title)
  • Last Modified (Date/Time)
  • Status (Published/Draft)
  • Owners (List of owner names)
• FR-004: The UI MUST provide a text filter input that filters the grid rows by Dashboard Name in real-time using client-side logic (fetching all dashboards once).
• FR-005: The grid MUST support multi-row selection to allow migrating batches of dashboards.
• FR-006: The selection state MUST be passed to the migration execution logic when the user initiates the migration.
• FR-007: The grid header MUST include a "Select All" checkbox. When checked, it MUST select ALL dashboards matching the current filter criteria (spanning across all pages), not just the currently visible page.
• FR-008: The grid MUST support pagination, displaying 20 rows per page by default, with navigation controls (Next/Prev/Page numbers).
• FR-009: The selection state MUST be preserved across filter changes. Items selected before a filter change MUST remain selected even if they are hidden by the new filter.

Key Entities

• Dashboard Metadata:
  • id: Unique identifier from Superset.
  • title: Display name.
  • changed_on: Timestamp of last edit.
  • is_published: Boolean status.
  • owners: List of owner objects/names.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can identify the status (Draft/Published) of any dashboard in the list with 100% accuracy.
• SC-002: Filtering a list of 100 dashboards takes less than 200ms to update the view.
• SC-003: Users can successfully select and initiate migration for a mix of Draft and Published dashboards in a single operation.