# 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 <repository-url>
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 '<temporary-secret>'
```

> Полный каталог переменных окружения — в [`.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).
