ss-tools

Инструменты автоматизации для Apache Superset: миграция, версионирование, аналитика и управление данными

📋 Содержание

• О проекте
• Возможности
• Архитектура
• Быстрый старт
• Документация
• Тестирование
• Покрытие кода
• Enterprise Clean Deployment
• Авторизация
• Мониторинг
• Вклад в проект
• Лицензия

📖 О проекте

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

✨ Возможности

🌐 LLM-перевод контента баз данных — главная фича

ss-tools умеет переводить данные прямо в вашей БД: сотни тысяч строк номенклатуры, спецификаций, паспортов изделий — за один прогон. Никакой ручной работы, никаких копипаст в Google Translate.

Как это работает: выбираете таблицу-источник, указываете колонки, задаёте целевые языки и LLM-провайдера. ss-tools читает данные, отправляет в LLM и пишет перевод обратно — напрямую в целевую таблицу или через Superset SQL Lab.

Ключевые возможности модуля:

• Multi-language одной LLM-сессией — одна строка переводится сразу на несколько языков (ru, en, de, fr, zh, kk и любые другие) в одном запросе к LLM. Экономия токенов и времени.
• Любой LLM-провайдер — Qwen, DeepSeek, GPT-4o, Claude, YandexGPT, GigaChat — всё, что совместимо с OpenAI API. Меняете модель в конфигурации джобы.
• Preview-воркфлоу — перед полноценным прогоном ss-tools показывает сэмпл перевода. Вы просматриваете строки, правите неудачные варианты, подтверждаете — и только потом запускаете полный прогон.
• Словари терминологии — загрузите CSV/TSV с правильными переводами ваших доменных терминов: «плавка → melt», «сортопрокат → bar stock», «ТУ → technical specifications». Словари автоматически подмешиваются в промпт, LLM использует именно вашу терминологию.
• Inline-коррекция — увидели плохой перевод в результатах? Правите прямо в UI, исправление улетает обратно в словарь. Каждый прогон делает систему умнее.
• Инкрементальный перевод — повторный прогон переводит только новые и изменившиеся строки (сравнение по хешу ключа). Уже переведённое не трогается.
• Автоопределение языка источника — не нужно указывать, на каком языке исходные данные. ss-tools определяет язык сам (через lingua-language-detector, без LLM — быстро и дёшево).
• Планировщик по cron — настроили джобу на еженочный прогон? Она будет запускаться автоматически. APScheduler под капотом.
• Cache-механизм — повторный перевод уже переведённого контента не тратит токены — результаты берутся из кэша.
• Аудит и метрики — каждый прогон логируется: сколько строк переведено, сколько пропущено, упало, сколько токенов потрачено, сколько результата взято из кэша. Всё в структурированных событиях.
• Bulk-замена — нашли, что LLM перевёл термин неконсистентно? Bulk find-and-replace по всем записям прогона.

Техническая справка: модуль перевода — это ~120+ файлов backend на Python, собственная оркестрация (планировщик → executor → batch processor → LLM call), 4 уровня ретраев с адаптивным batch-sizer'ом, async HTTP-клиент для OpenAI API, поддержка Direct SQL (INSERT/UPSERT) и Superset SQL Lab, система промптов с Jaccard-семантикой для подбора словарных статей. Frontend — 5 страниц (джобы, прогоны, словари), 15+ Svelte-компонентов, real-time WebSocket-прогресс.

🔄 Миграция данных без страха

Перенос дашбордов и датасетов между dev, staging и production — рутинная операция, которая обычно отнимает часы и чревата ошибками. ss-tools делает её предсказуемой:

• Dry-run режим — перед реальными изменениями вы получаете детальный отчёт: какие объекты будут затронуты, какие риски обнаружены, что изменится в целевой среде. Никаких сюрпризов.
• Автоматический маппинг БД — базы данных, ресурсы и идентификаторы сопоставляются между окружениями автоматически. Никакого ручного поиска и замены.
• Миграция legacy-данных — встроенная поддержка переноса из SQLite в PostgreSQL. Устаревшие хранилища не помеха.

🌿 Git-интеграция: дашборды как код

Хватит копировать дашборды через export/import. Включите их в свой Git-процесс:

• Версионирование — каждый дашборд — это файл в репозитории. Полная история изменений, откат на любую версию, diff любой сложности.
• LLM-управление ветками — создавайте ветки, коммитьте и сливайте изменения через natural language команды. «Создай ветку для эксперимента с отчётом по энергопотреблению и закоммить текущие дашборды».
• Деплой из Git — push в целевую ветку автоматически применяет изменения на нужном окружении. CI/CD для дашбордов.
• Интеллектуальные сообщения коммитов — LLM анализирует изменения и сам предлагает осмысленный заголовок коммита.

🤖 LLM-аналитика: ИИ присматривает за дашбордами

Не просто инструмент, а ваш ассистент по данным:

• Автовалидация дашбордов — LLM проверяет корректность метрик, источников данных и визуализаций. Нашёл подозрительный SQL в фильтре? Сообщит до того, как дашборд попадёт к пользователям.
• Генерация документации — для любого датасета создаётся человекочитаемое описание: какие поля, откуда данные, какие есть зависимости.
• Assistant API — управляйте ss-tools голосом или текстом на естественном языке. «Перенеси дашборд производства на staging», «Покажи историю изменений по датасету качества продукции».
• Умный коммитинг — LLM анализирует изменения и генерирует сообщение коммита, отражающее суть. Никаких «fix» и «update».

📊 Управление и мониторинг: полный контроль

Одна консоль, чтобы править всеми:

• RBAC — гибкая ролевая модель: admin, analyst, viewer. Каждый видит и делает только то, что ему разрешено.
• Фоновые задачи с WebSocket — запустили миграцию на час? Откройте Task Drawer и наблюдайте прогресс в реальном времени. Никаких логов, к которым нужно подключаться по SSH.
• Unified Reports — единый формат отчётов для всех типов задач. Один эндпоинт — любые данные.
• Аудит — каждое действие логируется. Кто, когда и что сделал — всегда можно выяснить.
• Retention-политики — артефакты автоматически очищаются по расписанию. Диски не забиваются.

🔌 Плагинная архитектура: расширяйте без границ

ss-tools спроектирован как платформа. Хотите свою логику миграции? Свой источник данных? Свой триггер?

Каждый модуль — это изолированный плагин:

Плагин	Назначение
TranslatePlugin	LLM-перевод контента БД
MigrationPlugin	Миграция дашбордов между окружениями
BackupPlugin	Резервное копирование и восстановление
GitPlugin	Полный цикл Git-операций
LLMAnalysisPlugin	AI-валидация и генерация документации
MapperPlugin	Маппинг колонок и ресурсов
DebugPlugin	Диагностика и профилирование системы
SearchPlugin	Полнотекстовый поиск по датасетам

Пишите свои плагины, подключайте через простой Python API. Никакой магии — только чёткий контракт.

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

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

Backend: Python 3.9+ (FastAPI, SQLAlchemy, APScheduler), PostgreSQL, GitPython, OpenAI API, 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/                      # Спецификации

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

Требования

• Docker (рекомендуется): Docker Engine 24+, Docker Compose v2, 4 GB RAM
• Локальная разработка: Python 3.9+, Node.js 18+, npm, 2 GB RAM, 5 GB диска

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

git clone <repository-url>
cd ss-tools
docker compose up --build

После запуска:

• Frontend: http://localhost:8000
• Backend API: http://localhost:8001
• PostgreSQL: localhost:5432

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

# 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

Начальная настройка

# Переменные окружения
cp .env.example backend/.env

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

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

Полный каталог переменных окружения — в .env.example.

Offline-бандл

# Загрузка образа
xz -dc dist/docker/ss-tools.20260517.tar.xz | docker load
export POSTGRES_PASSWORD="my-strong-password"
docker compose -f dist/docker/docker-compose.light.yml up -d

Сборка бандла: ./build.sh bundle:light v1.0.0 (light, ~104 MB) или ./build.sh bundle v1.0.0 (full).

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

• Установка и настройка
• Архитектура системы
• API документация
• Настройка окружений

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

Запуск тестов

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

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

# Конкретный тест
pytest tests/test_auth.py::test_create_user

📊 Покрытие кода

Сводный отчёт о покрытии генерируется скриптом scripts/coverage-summary.sh:

# Полный запуск (backend integration + frontend)
./scripts/coverage-summary.sh

# Backend unit-тесты (SQLite) + frontend (быстрее, не требует Docker)
./scripts/coverage-summary.sh --unit

# Только frontend
./scripts/coverage-summary.sh --frontend-only

# Только backend unit
./scripts/coverage-summary.sh --backend-only --unit

# Указать директорию для отчёта
./scripts/coverage-summary.sh --output-dir ./reports/coverage

Скрипт выполняет:

1. Запуск backend-тестов (pytest) с --cov=src — unit (--unit) или integration (--run-integration)
2. Запуск frontend-тестов (vitest) с --coverage
3. Парсинг результатов тестов и процентов покрытия
4. Генерацию единого HTML-отчёта в coverage-summary/index.html со сводкой по обоим стекам

Текущие показатели:

Стек	Тип тестов	Процент	Покрытие (Stmts)
Backend (unit)	1723	1721/2 ✅	48%
Backend (integration)	167	167/0 ✅	12%
Frontend	2443	2442/1 ✅	99.25%

HTML-отчёты coverage по каждому стеку открываются из сводного отчёта по ссылкам.

🏢 Enterprise Clean Deployment

Для разворота в корпоративной сети с очищенным дистрибутивом (без тестовых данных, с запретом внешних источников и обязательной compliance-проверкой) используется профиль enterprise clean.

Поддерживаются CLI, API и TUI flows. Подробная документация — в docs/enterprise-clean.md.

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

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

1. Локальная (username/password)
2. ADFS SSO (Active Directory Federation Services)

Управление пользователями и ролями — через POST /api/admin/users и POST /api/admin/roles. Документация — docs/installation.md.

📊 Мониторинг

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

API: GET /api/reports?page=1&page_size=20 (фильтры по статусу, типу, дате).

💻 Примеры скриптов

Примеры интеграции с внешними системами (Airflow, CI/CD, cron) — в examples/:

• Python
• Bash

Скрипты демонстрируют аутентификацию через API Key (X-API-Key), запуск и завершение maintenance-событий, обработку ошибок.

🤝 Вклад в проект

Мы приветствуем contributions! См. CONTRIBUTING.md.

📄 Лицензия

Проект распространяется под лицензией MIT.