chore: commit remaining workspace changes
This commit is contained in:
310
README.md
310
README.md
@@ -1,143 +1,253 @@
|
||||
# ss-tools
|
||||
|
||||
Инструменты автоматизации для Apache Superset: миграция, маппинг, хранение артефактов, Git-интеграция, отчеты по задачам и LLM-assistant.
|
||||
**Инструменты автоматизации для Apache Superset: миграция, версионирование, аналитика и управление данными**
|
||||
|
||||
## Возможности
|
||||
- Миграция дашбордов и датасетов между окружениями.
|
||||
- Ручной и полуавтоматический маппинг ресурсов.
|
||||
- Логи фоновых задач и отчеты о выполнении.
|
||||
- Локальное хранилище файлов и бэкапов.
|
||||
- Git-операции по Superset-ассетам через UI.
|
||||
- Модуль LLM-анализа и assistant API.
|
||||
- Многопользовательская авторизация (RBAC).
|
||||
## 📋 О проекте
|
||||
|
||||
## Стек
|
||||
- Backend: Python, FastAPI, SQLAlchemy, APScheduler.
|
||||
- Frontend: SvelteKit, Vite, Tailwind CSS.
|
||||
- База данных: PostgreSQL (основная конфигурация), поддержка миграции с legacy SQLite.
|
||||
ss-tools — это комплексная платформа для автоматизации работы с Apache Superset, предоставляющая инструменты для миграции дашбордов, управления версиями через Git, LLM-анализа данных и многопользовательского контроля доступа. Система построена на модульной архитектуре с плагинной системой расширений.
|
||||
|
||||
## Структура репозитория
|
||||
- `backend/` — API, плагины, сервисы, скрипты миграции и тесты.
|
||||
- `frontend/` — SPA-интерфейс (SvelteKit).
|
||||
- `docs/` — документация по архитектуре и плагинам.
|
||||
- `specs/` — спецификации и планы реализации.
|
||||
- `docker/` и `docker-compose.yml` — контейнеризация.
|
||||
### 🎯 Ключевые возможности
|
||||
|
||||
## Быстрый старт (локально)
|
||||
#### 🔄 Миграция данных
|
||||
- **Миграция дашбордов и датасетов** между окружениями (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 (рекомендуется)
|
||||
|
||||
### Запуск backend + frontend одним скриптом
|
||||
```bash
|
||||
./run.sh
|
||||
```
|
||||
# Клонирование репозитория
|
||||
git clone <repository-url>
|
||||
cd ss-tools
|
||||
|
||||
Что делает `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
|
||||
|
||||
### Запуск
|
||||
```bash
|
||||
# Запуск всех сервисов
|
||||
docker compose up --build
|
||||
|
||||
# После запуска:
|
||||
# Frontend: http://localhost:8000
|
||||
# Backend API: http://localhost:8001
|
||||
# PostgreSQL: localhost:5432
|
||||
```
|
||||
|
||||
После старта сервисы доступны по адресам:
|
||||
- Frontend: `http://localhost:8000`
|
||||
- Backend API: `http://localhost:8001`
|
||||
- PostgreSQL: `localhost:5432` (`postgres/postgres`, БД `ss_tools`)
|
||||
#### Вариант 2: Локально
|
||||
|
||||
### Остановка
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
### Очистка БД-тома
|
||||
```bash
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
### Альтернативный образ PostgreSQL
|
||||
Если есть проблемы с pull `postgres:16-alpine`:
|
||||
```bash
|
||||
POSTGRES_IMAGE=mirror.gcr.io/library/postgres:16-alpine docker compose up -d db
|
||||
```
|
||||
или
|
||||
```bash
|
||||
POSTGRES_IMAGE=bitnami/postgresql:latest docker compose up -d db
|
||||
```
|
||||
|
||||
Если порт `5432` занят:
|
||||
```bash
|
||||
POSTGRES_HOST_PORT=5433 docker compose up -d db
|
||||
```
|
||||
|
||||
## Разработка
|
||||
|
||||
### Ручной запуск сервисов
|
||||
```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
|
||||
```
|
||||
|
||||
В другом терминале:
|
||||
```bash
|
||||
# Frontend (в новом терминале)
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev -- --port 5173
|
||||
```
|
||||
|
||||
### Тесты
|
||||
Backend:
|
||||
```bash
|
||||
cd backend
|
||||
source .venv/bin/activate
|
||||
pytest
|
||||
```
|
||||
### Первичная настройка
|
||||
|
||||
Frontend:
|
||||
```bash
|
||||
cd frontend
|
||||
npm run test
|
||||
```
|
||||
|
||||
## Инициализация auth (опционально)
|
||||
```bash
|
||||
# Инициализация БД
|
||||
cd backend
|
||||
source .venv/bin/activate
|
||||
python src/scripts/init_auth_db.py
|
||||
|
||||
# Создание администратора
|
||||
python src/scripts/create_admin.py --username admin --password admin
|
||||
```
|
||||
|
||||
## Миграция legacy-данных (опционально)
|
||||
## 📖 Документация
|
||||
|
||||
- [Установка и настройка](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
|
||||
PYTHONPATH=. python src/scripts/migrate_sqlite_to_postgres.py --sqlite-path tasks.db
|
||||
pytest
|
||||
|
||||
# Frontend тесты
|
||||
cd frontend
|
||||
npm run test
|
||||
|
||||
# Запуск конкретного теста
|
||||
pytest tests/test_auth.py::test_create_user
|
||||
```
|
||||
|
||||
## Дополнительная документация
|
||||
- `docs/plugin_dev.md`
|
||||
- `docs/settings.md`
|
||||
- `semantic_protocol.md`
|
||||
|
||||
|
||||
## 🔐 Авторизация
|
||||
|
||||
Система поддерживает два метода аутентификации:
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user