ss-tools

Инструменты автоматизации для Apache Superset: миграция, маппинг, хранение артефактов, Git-интеграция, отчеты по задачам и LLM-assistant.

Возможности

• Миграция дашбордов и датасетов между окружениями.
• Ручной и полуавтоматический маппинг ресурсов.
• Логи фоновых задач и отчеты о выполнении.
• Локальное хранилище файлов и бэкапов.
• Git-операции по Superset-ассетам через UI.
• Модуль LLM-анализа и assistant API.
• Многопользовательская авторизация (RBAC).

Стек

• Backend: Python, FastAPI, SQLAlchemy, APScheduler.
• Frontend: SvelteKit, Vite, Tailwind CSS.
• База данных: PostgreSQL (основная конфигурация), поддержка миграции с legacy SQLite.

Структура репозитория

• backend/ — API, плагины, сервисы, скрипты миграции и тесты.
• frontend/ — SPA-интерфейс (SvelteKit).
• docs/ — документация по архитектуре и плагинам.
• specs/ — спецификации и планы реализации.
• docker/ и docker-compose.yml — контейнеризация.

Быстрый старт (локально)

Требования

• Python 3.9+
• Node.js 18+
• npm

Запуск backend + frontend одним скриптом

./run.sh

Что делает run.sh:

• проверяет версии Python/npm;
• создает backend/.venv (если нет);
• устанавливает backend/requirements.txt и frontend зависимости;
• запускает backend и frontend параллельно.

Опции:

• ./run.sh --skip-install — пропустить установку зависимостей.
• ./run.sh --help — показать справку.

Переменные окружения для локального запуска:

• BACKEND_PORT (по умолчанию 8000)
• FRONTEND_PORT (по умолчанию 5173)
• POSTGRES_URL
• DATABASE_URL
• TASKS_DATABASE_URL
• AUTH_DATABASE_URL

Docker

Запуск

docker compose up --build

После старта сервисы доступны по адресам:

• Frontend: http://localhost:8000
• Backend API: http://localhost:8001
• PostgreSQL: localhost:5432 (postgres/postgres, БД ss_tools)

Остановка

docker compose down

Очистка БД-тома

docker compose down -v

Альтернативный образ PostgreSQL

Если есть проблемы с pull postgres:16-alpine:

POSTGRES_IMAGE=mirror.gcr.io/library/postgres:16-alpine docker compose up -d db

или

POSTGRES_IMAGE=bitnami/postgresql:latest docker compose up -d db

Если порт 5432 занят:

POSTGRES_HOST_PORT=5433 docker compose up -d db

Разработка

Ручной запуск сервисов

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 -m uvicorn src.app:app --reload --port 8000

В другом терминале:

cd frontend
npm install
npm run dev -- --port 5173

Тесты

Backend:

cd backend
source .venv/bin/activate
pytest

Frontend:

cd frontend
npm run test

Инициализация auth (опционально)

cd backend
source .venv/bin/activate
python src/scripts/init_auth_db.py
python src/scripts/create_admin.py --username admin --password admin

Миграция legacy-данных (опционально)

cd backend
source .venv/bin/activate
PYTHONPATH=. python src/scripts/migrate_sqlite_to_postgres.py --sqlite-path tasks.db

Дополнительная документация

• docs/plugin_dev.md
• docs/settings.md
• semantic_protocol.md