ss-tools — это комплексная платформа для автоматизации работы с Apache Superset, предоставляющая инструменты для миграции дашбордов, управления версиями через Git, LLM-анализа данных и многопользовательского контроля доступа. Система построена на модульной архитектуре с плагинной системой расширений.

🎯 Ключевые возможности

🔄 Миграция данных

Миграция дашбордов и датасетов между окружениями (dev/staging/prod)
Dry-run режим с детальным анализом рисков и предпросмотром изменений
Автоматическое маппинг баз данных и ресурсов между окружениями
Поддержка legacy-данных с миграцией из SQLite в PostgreSQL

🌿 Git-интеграция

Версионирование дашбордов через Git-репозитории
Управление ветками и коммитами с помощью LLM
Деплой дашбордов из Git в целевые окружения
История изменений с детальным diff

🤖 LLM-аналитика

Автоматическая валидация дашбордов с помощью ИИ
Генерация документации для датасетов
Assistant API для natural language команд
Интеллектуальное коммитинг с подсказками сообщений

📊 Управление и мониторинг

Многопользовательская авторизация (RBAC)
Фоновые задачи с реальным логированием через WebSocket
Унифицированные отчеты по выполненным задачам
Хранение артефактов с политиками retention
Аудит логирование всех действий

🔌 Плагины

MigrationPlugin — миграция дашбордов
BackupPlugin — резервное копирование
GitPlugin — управление версиями
LLMAnalysisPlugin — аналитика и документация
MapperPlugin — маппинг колонок
DebugPlugin — диагностика системы
SearchPlugin — поиск по датасетам

🏗️ Архитектура

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

Backend:

Python 3.9+ (FastAPI, SQLAlchemy, APScheduler)
PostgreSQL (основная БД)
GitPython для Git-операций
OpenAI API для LLM-функций
Playwright для скриншотов

Frontend:

SvelteKit (Svelte 5.x)
Vite
Tailwind CSS
WebSocket для реального логирования

DevOps:

Docker & Docker Compose
PostgreSQL 16

Модульная структура

ss-tools/
├── backend/                    # Backend API
│   ├── src/
│   │   ├── api/               # API маршруты
│   │   ├── core/              # Ядро системы
│   │   │   ├── task_manager/  # Управление задачами
│   │   │   ├── auth/          # Авторизация
│   │   │   ├── migration/     # Миграция данных
│   │   │   └── plugins/       # Плагины
│   │   ├── models/            # Модели данных
│   │   ├── services/          # Бизнес-логика
│   │   └── schemas/           # Pydantic схемы
│   └── tests/                 # Тесты
├── frontend/                   # SvelteKit приложение
│   ├── src/
│   │   ├── routes/            # Страницы
│   │   ├── lib/
│   │   │   ├── components/    # UI компоненты
│   │   │   ├── stores/        # Svelte stores
│   │   │   └── api/           # API клиент
│   │   └── i18n/              # Мультиязычность
│   └── tests/
├── docker/                     # Docker конфигурация
├── docs/                       # Документация
└── specs/                      # Спецификации

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

Требования

Локальная разработка:

Python 3.9+
Node.js 18+
npm
2 GB RAM (минимум)
5 GB свободного места

Docker (рекомендуется):

Docker Engine 24+
Docker Compose v2
4 GB RAM (для стабильной работы)

Установка и запуск

Вариант 1: Docker (рекомендуется)

# Клонирование репозитория
git clone <repository-url>
cd ss-tools

# Запуск всех сервисов
docker compose up --build

# После запуска:
# Frontend: http://localhost:8000
# Backend API: http://localhost:8001
# PostgreSQL: localhost:5432

Вариант 2: Локально

# Backend
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 -m uvicorn src.app:app --reload --port 8000

# Frontend (в новом терминале)
cd frontend
npm install
npm run dev -- --port 5173

Первичная настройка

# Инициализация БД
cd backend
source .venv/bin/activate
python src/scripts/init_auth_db.py

# Создание администратора
python src/scripts/create_admin.py --username admin --password admin

🏢 Enterprise Clean Deployment (internal-only)

Для разворота в корпоративной сети используйте профиль enterprise clean:

очищенный дистрибутив без test/demo/load-test данных;
запрет внешних интернет-источников;
загрузка ресурсов только с внутренних серверов компании;
обязательная блокирующая проверка clean/compliance перед выпуском.

Быстрый запуск TUI-проверки:

cd /home/busya/dev/ss-tools
./backend/.venv/bin/python3 -m backend.src.scripts.clean_release_tui

Типовые внутренние источники:

repo.intra.company.local
artifacts.intra.company.local
pypi.intra.company.local

Если найден внешний endpoint, выпуск получает статус BLOCKED до исправления.

📖 Документация

🧪 Тестирование

# Backend тесты
cd backend
source .venv/bin/activate
pytest

# Frontend тесты
cd frontend
npm run test

# Запуск конкретного теста
pytest tests/test_auth.py::test_create_user

🔐 Авторизация

Система поддерживает два метода аутентификации:

Локальная аутентификация (username/password)
ADFS SSO (Active Directory Federation Services)

Управление пользователями и ролями

# Получение списка пользователей
GET /api/admin/users

# Создание пользователя
POST /api/admin/users
{
  "username": "newuser",
  "email": "user@example.com",
  "password": "password123",
  "roles": ["analyst"]
}

# Создание роли
POST /api/admin/roles
{
  "name": "analyst",
  "permissions": ["dashboards:read", "dashboards:write"]
}

📊 Мониторинг

Отчеты о задачах

# Список всех отчетов
GET /api/reports?page=1&page_size=20

# Детали отчета
GET /api/reports/{report_id}

# Фильтры
GET /api/reports?status=failed&task_type=validation&date_from=2024-01-01

Активность

Dashboard Hub — управление дашбордами с Git-статусом
Dataset Hub — управление датасетами с прогрессом маппинга
Task Drawer — мониторинг выполнения фоновых задач
Unified Reports — унифицированные отчеты по всем типам задач

🔄 Обновление системы

# Обновление Docker контейнеров
docker compose pull
docker compose up -d

# Обновление зависимостей Python
cd backend
source .venv/bin/activate
pip install -r requirements.txt --upgrade

# Обновление зависимостей Node.js
cd frontend
npm install

Languages

JavaScript 53.8%

Python 31.3%

Svelte 8.4%

Shell 6.3%

TypeScript 0.1%

README.md Unescape Escape

ss-tools

📋 О проекте