busya
ec6421de35
- Replace all occurrences of 'ss-tools' with 'superset-tools' in 104 files - Rename git bundle file ss-tools.bundle → superset-tools.bundle - Update .gitignore pattern accordingly - Preserve variable names (hasSsTools etc.) and code identifiers
310 lines
20 KiB
Markdown
Executable File
310 lines
20 KiB
Markdown
Executable File
# superset-tools
|
||
|
||
[](https://www.python.org/)
|
||
[](https://nodejs.org/)
|
||
[](LICENSE)
|
||
[](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).
|