# ss-tools

**Инструменты автоматизации для Apache Superset: миграция, версионирование, аналитика и управление данными**

## 📋 О проекте

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 (рекомендуется)

```bash
# Клонирование репозитория
git clone <repository-url>
cd ss-tools

# Запуск всех сервисов
docker compose up --build

# После запуска:
# Frontend: http://localhost:8000
# Backend API: http://localhost:8001
# PostgreSQL: localhost:5432
```

#### Вариант 2: Локально

```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
# Инициализация БД
cd backend
source .venv/bin/activate
python src/scripts/init_auth_db.py

# Создание администратора
python src/scripts/create_admin.py --username admin --password admin
```

## 🏢 Enterprise Clean Deployment (internal-only)

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

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

Быстрый запуск TUI-проверки:

```bash
cd /home/busya/dev/ss-tools
./backend/.venv/bin/python3 -m backend.src.scripts.clean_release_tui
```

Типовые внутренние источники:
- `repo.intra.company.local`
- `artifacts.intra.company.local`
- `pypi.intra.company.local`

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

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

- [Установка и настройка](docs/installation.md)
- [Архитектура системы](docs/architecture.md)
- [Разработка плагинов](docs/plugin_dev.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
```



## 🔐 Авторизация

Система поддерживает два метода аутентификации:

1. **Локальная аутентификация** (username/password)
2. **ADFS SSO** (Active Directory Federation Services)

### Управление пользователями и ролями

```bash
# Получение списка пользователей
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"]
}
```

## 📊 Мониторинг

### Отчеты о задачах

```bash
# Список всех отчетов
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** — унифицированные отчеты по всем типам задач

## 🔄 Обновление системы

```bash
# Обновление 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
```