# superset-tools [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue?logo=python)](https://www.python.org/) [![Node 18+](https://img.shields.io/badge/node-18+-green?logo=node.js)](https://nodejs.org/) [![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE) [![Docker](https://img.shields.io/badge/docker-24+-blue?logo=docker)](https://www.docker.com/) **Инструменты автоматизации для Apache Superset: миграция, версионирование, аналитика и управление данными** ## 📋 Содержание - [О проекте](#-о-проекте) - [Возможности](#-возможности) - [Архитектура](#-архитектура) - [Быстрый старт](#-быстрый-старт) - [Документация](#-документация) - [Тестирование](#-тестирование) - [Покрытие кода](#-покрытие-кода) - [Enterprise Clean Deployment](#-enterprise-clean-deployment) - [Авторизация](#-авторизация) - [Мониторинг](#-мониторинг) - [Вклад в проект](#-вклад-в-проект) - [Лицензия](#-лицензия) ## 📖 О проекте superset-tools — комплексная платформа для автоматизации работы с Apache Superset, предоставляющая инструменты для LLM-перевода контента баз данных, миграции дашбордов, управления версиями через Git, LLM-аналитики и многопользовательского контроля доступа. Система построена на модульной архитектуре с плагинной системой расширений. ## ✨ Возможности ### 🌐 LLM-перевод контента баз данных — главная фича superset-tools умеет переводить данные прямо в вашей БД: сотни тысяч строк номенклатуры, спецификаций, паспортов изделий — за один прогон. Никакой ручной работы, никаких копипаст в Google Translate. Как это работает: выбираете таблицу-источник, указываете колонки, задаёте целевые языки и LLM-провайдера. superset-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-воркфлоу** — перед полноценным прогоном superset-tools показывает сэмпл перевода. Вы просматриваете строки, правите неудачные варианты, подтверждаете — и только потом запускаете полный прогон. - **Словари терминологии** — загрузите CSV/TSV с правильными переводами ваших доменных терминов: «плавка → melt», «сортопрокат → bar stock», «ТУ → technical specifications». Словари автоматически подмешиваются в промпт, LLM использует именно вашу терминологию. - **Inline-коррекция** — увидели плохой перевод в результатах? Правите прямо в UI, исправление улетает обратно в словарь. Каждый прогон делает систему умнее. - **Инкрементальный перевод** — повторный прогон переводит только новые и изменившиеся строки (сравнение по хешу ключа). Уже переведённое не трогается. - **Автоопределение языка источника** — не нужно указывать, на каком языке исходные данные. superset-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 — рутинная операция, которая обычно отнимает часы и чревата ошибками. superset-tools делает её предсказуемой: - **Dry-run режим** — перед реальными изменениями вы получаете детальный отчёт: какие объекты будут затронуты, какие риски обнаружены, что изменится в целевой среде. Никаких сюрпризов. - **Автоматический маппинг БД** — базы данных, ресурсы и идентификаторы сопоставляются между окружениями автоматически. Никакого ручного поиска и замены. - **Миграция legacy-данных** — встроенная поддержка переноса из SQLite в PostgreSQL. Устаревшие хранилища не помеха. ### 🌿 Git-интеграция: дашборды как код Хватит копировать дашборды через export/import. Включите их в свой Git-процесс: - **Версионирование** — каждый дашборд — это файл в репозитории. Полная история изменений, откат на любую версию, diff любой сложности. - **LLM-управление ветками** — создавайте ветки, коммитьте и сливайте изменения через natural language команды. «Создай ветку для эксперимента с отчётом по энергопотреблению и закоммить текущие дашборды». - **Деплой из Git** — push в целевую ветку автоматически применяет изменения на нужном окружении. CI/CD для дашбордов. - **Интеллектуальные сообщения коммитов** — LLM анализирует изменения и сам предлагает осмысленный заголовок коммита. ### 🤖 LLM-аналитика: ИИ присматривает за дашбордами Не просто инструмент, а ваш ассистент по данным: - **Автовалидация дашбордов** — LLM проверяет корректность метрик, источников данных и визуализаций. Нашёл подозрительный SQL в фильтре? Сообщит до того, как дашборд попадёт к пользователям. - **Генерация документации** — для любого датасета создаётся человекочитаемое описание: какие поля, откуда данные, какие есть зависимости. - **Assistant API** — управляйте superset-tools голосом или текстом на естественном языке. «Перенеси дашборд производства на staging», «Покажи историю изменений по датасету качества продукции». - **Умный коммитинг** — LLM анализирует изменения и генерирует сообщение коммита, отражающее суть. Никаких «fix» и «update». ### 📊 Управление и мониторинг: полный контроль Одна консоль, чтобы править всеми: - **RBAC** — гибкая ролевая модель: admin, analyst, viewer. Каждый видит и делает только то, что ему разрешено. - **Фоновые задачи с WebSocket** — запустили миграцию на час? Откройте Task Drawer и наблюдайте прогресс в реальном времени. Никаких логов, к которым нужно подключаться по SSH. - **Unified Reports** — единый формат отчётов для всех типов задач. Один эндпоинт — любые данные. - **Аудит** — каждое действие логируется. Кто, когда и что сделал — всегда можно выяснить. - **Retention-политики** — артефакты автоматически очищаются по расписанию. Диски не забиваются. ### 🔌 Плагинная архитектура: расширяйте без границ superset-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 ### Модульная структура ``` superset-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 (рекомендуется) ```bash git clone cd superset-tools docker compose up --build ``` После запуска: - Frontend: http://localhost:8000 - Backend API: http://localhost:8001 - PostgreSQL: localhost:5432 ### Локальная разработка ```bash # 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 ``` ### Начальная настройка ```bash # Переменные окружения 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 '' ``` > Полный каталог переменных окружения — в [`.env.example`](.env.example). ### Offline-бандл ```bash # Загрузка образа xz -dc dist/docker/superset-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). ## 📖 Документация - [Установка и настройка](docs/installation.md) - [Архитектура системы](docs/architecture.md) - [API документация](http://localhost:8001/docs) - [Настройка окружений](docs/settings.md) ## 🧪 Тестирование ### Запуск тестов ```bash # 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`: ```bash # Полный запуск (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](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/`](./examples/): - [Python](examples/maintenance-api-python.py) - [Bash](examples/maintenance-api-bash.sh) Скрипты демонстрируют аутентификацию через API Key (`X-API-Key`), запуск и завершение maintenance-событий, обработку ошибок. ## 🤝 Вклад в проект Мы приветствуем contributions! См. [CONTRIBUTING.md](CONTRIBUTING.md). ## 📄 Лицензия Проект распространяется под лицензией [MIT](LICENSE).