Feature Specification: Backend Refactoring - Remove superset_tool

Feature Branch: 012-remove-superset-tool
Created: 2026-01-22
Status: Draft
Input: User description: "нужен рефакторинг бека - я хочу исключить модуль superset_tool, пусть останется только backend"

Clarifications

Session 2026-01-22

Q: How should we reconcile the SupersetConfig model from superset_tool with the Environment model in the backend? → A: Merge all SupersetConfig fields (e.g., verify_ssl, timeout) into the Environment model in backend/src/core/config_models.py.
Q: Where should the utility modules from superset_tool/utils/ be moved within the backend/src/core/ directory? → A: Flatten them directly into backend/src/core/utils/ alongside existing utilities.
Q: Should interactive CLI utilities (whiptail_fallback.py, migration_script.py) be migrated? → A: No, deprecate them and do not migrate CLI-specific interactive UI logic to the backend.
Q: How should we handle SupersetLogger and belief_scope? → A: Consolidate all logging into backend/src/core/logger.py and remove the redundant SupersetLogger class.

User Scenarios & Testing (mandatory)

User Story 1 - Maintain Core Functionality (Priority: P1)

As a developer, I want to remove the redundant superset_tool module and merge its essential logic into the backend package so that the codebase is easier to maintain and deploy.

Why this priority: This is a critical architectural cleanup. The existence of two overlapping modules (superset_tool and backend/src/core/superset_client.py) creates confusion and potential bugs.

Independent Test: The application (FastAPI backend) should start and perform all Superset-related operations (fetching dashboards, datasets, etc.) without the superset_tool directory present in the root.

Acceptance Scenarios:

Given the superset_tool directory is deleted, When I run the backend server, Then it should start without ModuleNotFoundError.
Given the backend is running, When I trigger a dashboard list refresh in the UI, Then the backend should successfully fetch data from Superset using the migrated client logic.
Given a migration task, When I execute it, Then it should successfully use the consolidated SupersetClient to interact with the API.

User Story 2 - Unified Configuration and Models (Priority: P2)

As a developer, I want to use a single set of Pydantic models and configuration logic within the backend package instead of relying on external superset_tool.models.

Why this priority: Eliminates duplicate definitions and ensures consistency across the backend.

Independent Test: Verify that backend/src/core/config_models.py (or equivalent) contains all necessary fields previously defined in superset_tool/models.py.

Acceptance Scenarios:

Given a connection configuration in the database, When the backend loads it, Then it should correctly instantiate the consolidated configuration models.

Edge Cases

Deprecated Scripts: CLI-only scripts like migration_script.py and run_mapper.py in the root will be deprecated and removed as their logic is now in the web UI.
Dependency Conflicts: How does the system handle potential version conflicts between backend/requirements.txt and superset_tool/requirements.txt?
Environment Variables: Ensure that any environment variables previously used by superset_tool are still correctly loaded by the consolidated client.

Requirements (mandatory)

Functional Requirements

FR-001: The system MUST NOT depend on the superset_tool top-level module.
FR-002: All essential logic from superset_tool/client.py MUST be migrated to backend/src/core/superset_client.py. Utility modules from superset_tool/utils/ (network, fileio, dataset_mapper) MUST be migrated to backend/src/core/utils/.
FR-003: backend/src/core/superset_client.py MUST be refactored to be a self-contained client that doesn't inherit from superset_tool.client.BaseSupersetClient.
FR-004: Redundant logging logic (SupersetLogger) MUST be removed in favor of backend/src/core/logger.py.
FR-004: The backend's requirements.txt MUST be updated to include any dependencies previously required by superset_tool (e.g., requests, pyyaml).
FR-005: All imports in backend/src/ that reference superset_tool MUST be updated to reference the new locations within the backend.

Key Entities (include if feature involves data)

SupersetClient: The consolidated class responsible for all interactions with the Superset REST API.
Environment: The unified configuration model for Superset connections, incorporating legacy SupersetConfig fields.

Success Criteria (mandatory)

Measurable Outcomes

SC-001: Zero references to superset_tool in the backend/ source code.
SC-002: 100% of existing Superset integration tests pass after the refactoring.
SC-003: The superset_tool/ directory can be safely deleted from the repository.
SC-004: Backend startup time remains unaffected or improves slightly due to simplified import structure.

5.2 KiB Raw Blame History