ss-tools/README.md

Инструменты автоматизации Superset (ss-tools)

Обзор

ss-tools — это современная платформа для автоматизации и управления экосистемой Apache Superset. Проект перешел от набора CLI-скриптов к полноценному веб-приложению с архитектурой Backend (FastAPI) + Frontend (SvelteKit), обеспечивая удобный интерфейс для сложных операций.

Основные возможности

🚀 Миграция и управление дашбордами

• Dashboard Grid: Удобный просмотр всех дашбордов во всех окружениях (Dev, Sandbox, Prod) в едином интерфейсе.
• Интеллектуальный маппинг: Автоматическое и ручное сопоставление датасетов, таблиц и схем при переносе между окружениями.
• Проверка зависимостей: Валидация наличия всех необходимых компонентов перед миграцией.

📦 Резервное копирование

• Планировщик (Scheduler): Автоматическое создание резервных копий дашбордов и датасетов по расписанию.
• Хранилище: Локальное хранение артефактов с возможностью управления через UI.

🛠 Git Интеграция

• Version Control: Возможность версионирования ассетов Superset.
• Git Dashboard: Управление ветками, коммитами и деплоем изменений напрямую из интерфейса.
• Conflict Resolution: Встроенные инструменты для разрешения конфликтов в YAML-конфигурациях.

🤖 LLM Анализ (AI Plugin)

• Автоматический аудит: Анализ состояния дашбордов на основе скриншотов и метаданных.
• Генерация документации: Автоматическое описание датасетов и колонок с помощью LLM (OpenAI, OpenRouter и др.).
• Smart Validation: Поиск аномалий и ошибок в визуализациях.

🔐 Безопасность и администрирование

• Multi-user Auth: Многопользовательский доступ с ролевой моделью (RBAC).
• Управление подключениями: Централизованная настройка доступов к различным инстансам Superset.
• Логирование: Подробная история выполнения всех фоновых задач.

Технологический стек

• Backend: Python 3.9+, FastAPI, SQLAlchemy, APScheduler, Pydantic.
• Frontend: Node.js 18+, SvelteKit, Tailwind CSS.
• Database: PostgreSQL (для хранения метаданных, задач, логов и конфигурации).

Структура проекта

• backend/ — Серверная часть, API и логика плагинов.
• frontend/ — Клиентская часть (SvelteKit приложение).
• specs/ — Спецификации функций и планы реализации.
• docs/ — Дополнительная документация по маппингу и разработке плагинов.

Быстрый старт

Требования

• Python 3.9+
• Node.js 18+
• Настроенный доступ к API Superset

Запуск

Для автоматической настройки окружений и запуска обоих серверов (Backend & Frontend) используйте скрипт:

./run.sh

Скрипт создаст виртуальное окружение Python, установит зависимости pip и npm, и запустит сервисы.

Опции:

• --skip-install: Пропустить установку зависимостей.
• --help: Показать справку.

Переменные окружения:

• BACKEND_PORT: Порт API (по умолчанию 8000).
• FRONTEND_PORT: Порт UI (по умолчанию 5173).
• POSTGRES_URL: Базовый URL PostgreSQL по умолчанию для всех подсистем.
• DATABASE_URL: URL основной БД (если не задан, используется POSTGRES_URL).
• TASKS_DATABASE_URL: URL БД задач/логов (если не задан, используется DATABASE_URL).
• AUTH_DATABASE_URL: URL БД авторизации (если не задан, используется PostgreSQL дефолт).

Разработка

Проект следует строгим правилам разработки:

1. Semantic Code Generation: Использование протокола .ai/standards/semantics.md для обеспечения надежности кода.
2. Design by Contract (DbC): Определение предусловий и постусловий для ключевых функций.
3. Constitution: Соблюдение правил, описанных в конституции проекта в папке .specify/.

Полезные команды

• Backend: cd backend && .venv/bin/python3 -m uvicorn src.app:app --reload
• Frontend: cd frontend && npm run dev
• Тесты: cd backend && .venv/bin/pytest

Docker и CI/CD

Локальный запуск в Docker (приложение + PostgreSQL)

docker compose up --build

После старта:

• UI/API: http://localhost:8000
• PostgreSQL: localhost:5432 (postgres/postgres, DB ss_tools)

Остановить:

docker compose down

Полная очистка тома БД:

docker compose down -v

Если postgres:16-alpine не тянется из Docker Hub (TLS timeout), используйте fallback image:

POSTGRES_IMAGE=mirror.gcr.io/library/postgres:16-alpine docker compose up -d db

или:

POSTGRES_IMAGE=bitnami/postgresql:latest docker compose up -d db

Если на хосте уже занят 5432, поднимайте Postgres на другом порту:

POSTGRES_HOST_PORT=5433 docker compose up -d db

Миграция legacy-данных в PostgreSQL

Если нужно перенести старые данные из tasks.db/config.json:

cd backend
PYTHONPATH=. .venv/bin/python src/scripts/migrate_sqlite_to_postgres.py --sqlite-path tasks.db

CI/CD

Добавлен workflow: .github/workflows/ci-cd.yml

• backend smoke tests
• frontend build
• docker build
• push образа в GHCR на main/master

Контакты и вклад

Для добавления новых функций или исправления ошибок, пожалуйста, ознакомьтесь с docs/plugin_dev.md и создайте соответствующую спецификацию в specs/.