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

# При первом запуске будет создан backend/.env с ENCRYPTION_KEY

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

🏢 Enterprise Clean Deployment (internal-only)

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

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

Операционный workflow (CLI/API/TUI)

1) Headless flow через CLI (рекомендуется для CI/CD)

cd backend

# 1. Регистрация кандидата
.venv/bin/python3 -m src.scripts.clean_release_cli candidate-register \
  --candidate-id 2026.03.09-rc1 \
  --version 1.0.0 \
  --source-snapshot-ref git:release/2026.03.09-rc1 \
  --created-by release-operator

# 2. Импорт артефактов
.venv/bin/python3 -m src.scripts.clean_release_cli artifact-import \
  --candidate-id 2026.03.09-rc1 \
  --artifact-id artifact-001 \
  --path backend/dist/package.tar.gz \
  --sha256 deadbeef \
  --size 1024

# 3. Сборка манифеста
.venv/bin/python3 -m src.scripts.clean_release_cli manifest-build \
  --candidate-id 2026.03.09-rc1 \
  --created-by release-operator

# 4. Запуск compliance
.venv/bin/python3 -m src.scripts.clean_release_cli compliance-run \
  --candidate-id 2026.03.09-rc1 \
  --actor release-operator

2) API flow (автоматизация через сервисы)

V2 candidate/artifact/manifest API:
- POST /api/clean-release/candidates
- POST /api/clean-release/candidates/{candidate_id}/artifacts
- POST /api/clean-release/candidates/{candidate_id}/manifests
- GET /api/clean-release/candidates/{candidate_id}/overview
Legacy compatibility API (оставлены для миграции клиентов):
- POST /api/clean-release/candidates/prepare
- POST /api/clean-release/checks
- GET /api/clean-release/checks/{check_run_id}

3) TUI flow (тонкий клиент поверх facade)

cd /home/busya/dev/ss-tools
./run_clean_tui.sh 2026.03.09-rc1

Горячие клавиши:

F5: Run Compliance
F6: Build Manifest
F7: Reset Draft
F8: Approve
F9: Publish
F10: Refresh Overview

Важно: TUI требует валидный TTY. Без TTY запуск отклоняется с инструкцией использовать CLI/API.

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

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

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

Docker release для изолированного контура

Текущий enterprise clean профиль уже задаёт policy-level ограничения для внутреннего контура. Следующий логичный шаг для релизного процесса — выпускать не только application artifacts, но и готовый Docker bundle для разворота без доступа в интернет.

Целевой состав offline release-пакета:

backend image с уже установленными Python-зависимостями;
frontend image с уже собранным SvelteKit bundle;
postgres image или внутренний pinned base image;
docker-compose.enterprise-clean.yml для запуска в air-gapped окружении;
.env.enterprise-clean.example с обязательными переменными;
manifest с версиями, sha256 и перечнем образов;
инструкции по docker load / docker compose up без обращения к внешним registry.

Рекомендуемый workflow для такого релиза:

# 1. Собрать образы в подключённом контуре
./scripts/build_offline_docker_bundle.sh v1.0.0-rc2-docker

# 2. Передать dist/docker/* в изолированный контур
# 3. Импортировать образы локально
docker load -i dist/docker/backend.v1.0.0-rc2-docker.tar
docker load -i dist/docker/frontend.v1.0.0-rc2-docker.tar
docker load -i dist/docker/postgres.v1.0.0-rc2-docker.tar

# 4. Подготовить env из шаблона
cp dist/docker/.env.enterprise-clean.example .env.enterprise-clean

# 4a. Для первого запуска задать bootstrap администратора
# INITIAL_ADMIN_CREATE=true
# INITIAL_ADMIN_USERNAME=<org-admin-login>
# INITIAL_ADMIN_PASSWORD=<temporary-strong-secret>

# 5. Запустить только локальные образы
docker compose --env-file .env.enterprise-clean -f dist/docker/docker-compose.enterprise-clean.yml up -d

Bootstrap администратора выполняется entrypoint-скриптом внутри backend container:

если INITIAL_ADMIN_CREATE=true, контейнер вызывает create_admin.py перед стартом API;
если администратор уже существует, учётная запись не меняется;
теги в .env.enterprise-clean.example должны совпадать с фактически загруженными образами ss-tools-backend:v1.0.0-rc2-docker и ss-tools-frontend:v1.0.0-rc2-docker;
после первого входа пароль должен быть ротирован, а INITIAL_ADMIN_CREATE возвращён в false.

Ограничения для production-grade offline release:

build не должен тянуть зависимости в изолированном контуре;
все base images должны быть заранее зеркалированы во внутренний registry или поставляться как tar;
runtime-конфигурация не должна ссылаться на внешние API/registry/telemetry endpoints;
clean/compliance manifest должен включать docker image digests как часть evidence package.

Практический план внедрения:

pinned Docker image tags и отдельный enterprise-clean compose profile добавлены;
shell script scripts/build_offline_docker_bundle.sh добавлен для build -> save -> checksum;
следующим шагом стоит включить docker image digests в clean-release manifest;
следующим шагом стоит добавить smoke-check, что compose-файлы не содержат внешних registry references вне allowlist.

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

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

# 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

📋 О проекте