ss-tools/specs/024-user-dashboard-filter/spec.md

Feature Specification: User Profile Dashboard Filter

Feature Branch: 024-user-dashboard-filter
Created: 2026-03-04
Status: Draft
Input: User description: "Необходимо добавить страницу пользовательского профиля. В странице стоит указать следующие настройки - показывать по умолчанию только мои дашборды. Для этого в настройках следует указать поле для аккаунта Apache Superset, и дальше фильтровать все дашборды по имени owners | modified_by"

Clarifications

Session 2026-03-04

• Q: How should username mapping work if users switch between different Superset environments? → A: One global Superset username for all environments.
• Q: What exact filter logic should be used for owners and modified_by? → A: Include dashboard if username matches owners OR modified_by.
• Q: How should username matching work between saved profile username and dashboard fields? → A: Compare case-insensitively and trim surrounding spaces.
• Q: Who is allowed to edit the dashboard filter settings on the profile page? → A: Only the logged-in user can edit their own profile settings.
• Q: Where should the default "my dashboards" filter be applied in the product? → A: Only on the main dashboards list page.
• Q: Should profile binding support querying Apache Superset accounts from a selected environment? → A: Yes, provide account lookup from Superset environment during account binding.

User Scenarios & Testing (mandatory)

User Story 1 - Configure Dashboard Filter Preference (Priority: P1)

As a data analyst working with Apache Superset dashboards, I want to configure my profile to show only dashboards I own or have modified, so that I can quickly access my work without scrolling through irrelevant dashboards.

Why this priority: This is the core value of the feature - personalization of the dashboard view to improve user productivity. Without this, the feature provides no value.

Independent Test: Can be fully tested by navigating to the profile page, entering a Superset username, enabling the filter, saving preferences, and verifying that only matching dashboards appear in the dashboard list.

Acceptance Scenarios:

1. Given the user is on their profile page, When they enter a valid Apache Superset username and enable "Show only my dashboards", Then the system saves their preference and applies the filter to the dashboard list
2. Given the user has saved their filter preference, When they navigate to the dashboard list, Then only dashboards where they are listed as owner or modifier are displayed
3. Given the user has enabled the filter, When they disable it and save, Then the dashboard list shows all available dashboards again
4. Given the user is binding their Apache Superset account, When they select a Superset environment in profile settings, Then the system loads available Superset accounts and allows selecting one for binding
5. Given the user enters an invalid username format, When they attempt to save, Then the system displays a validation error and prevents saving

---

User Story 2 - Manage Profile Settings (Priority: P2)

As a user, I want to access and modify my profile settings from a dedicated page, so that I can control my dashboard viewing preferences at any time.

Why this priority: While essential for the feature to work, this is a supporting capability that enables the core filtering functionality. It can be implemented alongside the filtering logic.

Independent Test: Can be tested by navigating to the profile page, viewing current settings, making changes, and verifying persistence across sessions.

Acceptance Scenarios:

1. Given the user has previously saved their preferences, When they navigate to the profile page, Then their current settings are displayed (username and filter toggle state)
2. Given the user is on the profile page, When they click "Cancel" without saving changes, Then their previous settings remain unchanged
3. Given the user modifies their settings, When they click "Save", Then the changes persist and are reflected immediately in the dashboard list
4. Given a user attempts to edit another user's profile settings, When they submit changes, Then the system denies the action and keeps the target user's settings unchanged

---

User Story 3 - Override Dashboard Filter (Priority: P3)

As a user, I want to temporarily view all dashboards even when my filter is enabled, so that I can explore dashboards owned by others when needed.

Why this priority: This enhances usability by providing flexibility. Users may occasionally need to see all dashboards without permanently changing their preference.

Independent Test: Can be tested by having a filter enabled, then using a clear/remove filter option on the dashboard list to temporarily show all dashboards.

Acceptance Scenarios:

1. Given the user has enabled "Show only my dashboards", When they click the filter indicator on the dashboard list, Then all dashboards are displayed and the filter is temporarily disabled
2. Given the user has temporarily disabled the filter, When they navigate away and return to the dashboard list, Then their original filter preference is still applied

---

Edge Cases

• What happens when the user's Superset username is changed in Apache Superset after they've configured their filter?
• How does the system handle a user who has no dashboards as owner or modifier?
• What happens when the Apache Superset connection is unavailable when the user tries to save preferences?
• How does the system handle special characters or very long usernames?
• What happens when one user has different usernames across Superset environments?
• How does the system behave if the Superset account lookup request fails or returns partial data?
• How does the system behave if the user has never configured their profile settings?

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST provide a user profile page accessible from the main application interface
• FR-002: Profile page MUST include a text input field for Apache Superset username
• FR-003: Profile page MUST include a toggle control for "Show only my dashboards by default" setting
• FR-004: System MUST validate that the username field is not empty when the filter toggle is enabled
• FR-005: System MUST validate that the username does not contain spaces or invalid characters
• FR-006: System MUST persist user profile settings across sessions
• FR-007: When the filter is enabled, dashboard list MUST include a dashboard if the user's username matches the owners field OR the modified_by field
• FR-008: When the filter is enabled, dashboard list MUST exclude dashboards where the user's username matches neither owners nor modified_by
• FR-009: System MUST apply the filter immediately after saving profile preferences on the main dashboards list page
• FR-010: Dashboard list MUST display a visual indicator when a filter is active
• FR-011: System MUST allow users to temporarily clear the filter from the dashboard list view
• FR-012: System MUST restore the user's filter preference when returning to the dashboard list after temporarily clearing it
• FR-013: System MUST display appropriate error messages when settings cannot be saved
• FR-014: System MUST display a success confirmation when settings are saved successfully
• FR-015: System MUST handle the case where no dashboards match the filter criteria with an appropriate empty state message
• FR-016: System MUST use one global Apache Superset username per user profile across all Superset environments
• FR-017: System MUST match usernames using case-insensitive comparison after trimming leading and trailing spaces in both saved username and dashboard fields
• FR-018: System MUST allow users to edit only their own dashboard filter settings and MUST prevent edits to other users' settings
• FR-019: System MUST NOT auto-apply this default filter outside the main dashboards list page
• FR-020: While binding Apache Superset account in profile settings, system MUST allow selecting a Superset environment for account lookup
• FR-021: For selected environment, system MUST request and display available Superset accounts for user selection during binding
• FR-022: If Superset account lookup is unavailable, system MUST show a non-blocking error and allow manual username entry

Key Entities

• User Profile: Stores user preferences including one global Apache Superset username and dashboard filter setting. Key attributes: username (text, global across environments), show_only_my_dashboards (boolean)
• Dashboard: Represents an Apache Superset dashboard. Key attributes: dashboard_id, title, owner (username), modified_by (username), last_modified_date
• Filter Preference: Represents the user's saved filtering behavior. Key attributes: enabled (boolean), username (text), filter_type (owners_or_modified_by)
• Superset Account Candidate: Represents an account returned from selected Superset environment lookup for profile binding. Key attributes: environment_id, username, display_name

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can configure their dashboard filter preference in under 30 seconds
• SC-002: After saving preferences, users see the dashboard list update to the filtered view within 2 seconds
• SC-003: 95% of users successfully save their profile settings on first attempt
• SC-004: Users report a 50% reduction in time spent finding their dashboards in surveys
• SC-005: During peak usage, users can save preferences reliably without noticeable slowdowns
• SC-006: Filter correctly identifies user-owned dashboards with 99% accuracy based on owner and modified_by fields
• SC-007: Profile settings persist correctly across 100% of user sessions

Assumptions

• Users have an existing Apache Superset account with a unique username
• The application can access dashboard metadata that includes owner and modified_by identifiers
• The application has an existing user authentication system that can be extended with profile settings
• Dashboard list page exists and can be modified to support filtering
• Apache Superset username format follows standard conventions (alphanumeric, underscores, hyphens allowed)
• Each user has one global Superset username that is used in all environments
• Configured Superset environments expose account listing data that can be queried during profile binding