From e62735cc06cb00ae71001c552f9eb83b7c3862ca Mon Sep 17 00:00:00 2001 From: busya Date: Thu, 23 Jul 2026 12:33:19 +0300 Subject: [PATCH] docs: refresh business overview and installation guide --- INSTALL.md | 419 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 466 ++++++++++++++++------------------------------------- 2 files changed, 561 insertions(+), 324 deletions(-) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 000000000..c60b5e888 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,419 @@ +# Установка и настройка superset-tools + +## Содержание + +- [Требования](#требования) +- [Архитектура](#архитектура) +- [Технологический стек](#технологический-стек) +- [Docker (рекомендуется)](#docker-рекомендуется) +- [Локальная разработка](#локальная-разработка) +- [Конфигурация](#конфигурация) +- [AI-агент](#ai-агент) +- [Система сборки](#система-сборки) +- [Тестирование](#тестирование) +- [Покрытие кода](#покрытие-кода) +- [SSL/TLS конфигурация](#ssltls-конфигурация) +- [Enterprise Clean Deployment](#enterprise-clean-deployment) +- [Спецификации](#спецификации) +- [Утилиты](#утилиты) +- [Исследования](#исследования) + +## Требования + +- **Docker (рекомендуется):** Docker Engine 24+, Docker Compose v2, 4 GB RAM +- **Локальная разработка:** Python 3.9+, Node.js 18+, npm, 2 GB RAM, 5 GB диска + +## Архитектура + +Проект состоит из трёх сервисов: + +| Сервис | Технологии | Назначение | +|---|---|---| +| **backend/** | Python FastAPI, SQLAlchemy 2.0, APScheduler, PostgreSQL | REST API, бизнес-логика, плагины | +| **frontend/** | Svelte 5 (Runes), SvelteKit, Vite, Tailwind CSS | SPA-клиент | +| **agent/** | Gradio, LangGraph, LangChain, OpenAI SDK | AI-агент с чат-интерфейсом | +| **shared/** | Python package | Общие утилиты (логирование, SSL, LLM HTTP) | + +``` +superset-tools/ +├── backend/ # REST API (FastAPI) +│ ├── src/ +│ │ ├── api/routes/ # 30+ роутов (admin, auth, translate, git, agent...) +│ │ ├── core/ +│ │ │ ├── auth/ # JWT, OAuth, API Keys, RBAC +│ │ │ ├── migration/ # Dry-run, risk assessment +│ │ │ ├── task_manager/ # Async jobs, event bus, persistence +│ │ │ ├── superset_client/ +│ │ │ ├── logger/ # Structured logging, belief state +│ │ │ └── ... +│ │ ├── models/ # SQLAlchemy модели +│ │ ├── plugins/ # Реализации плагинов +│ │ ├── schemas/ # Pydantic схемы +│ │ ├── services/ # Бизнес-логика +│ │ └── scripts/ # CLI/TUI админ-скрипты +│ └── tests/ +├── frontend/ # SvelteKit SPA +│ ├── src/ +│ │ ├── routes/ # 20+ групп страниц +│ │ ├── lib/ +│ │ │ ├── api/ # API клиент +│ │ │ ├── auth/ # Auth store, permissions +│ │ │ ├── components/ # UI компоненты +│ │ │ ├── stores/ # Svelte stores +│ │ │ ├── i18n/ # Мультиязычность +│ │ │ └── ... +│ │ └── ... +│ └── tests/ +├── agent/ # Gradio/LangGraph AI-агент +│ ├── src/ss_tools/agent/ +│ │ ├── app.py # Gradio приложение +│ │ ├── langgraph_setup.py # LangGraph граф +│ │ ├── tools.py # LangChain инструменты +│ │ ├── document_parser.py # PDF/XLSX парсер +│ │ └── ... +│ └── tests/ +├── shared/ # Общий Python пакет (ss-tools-shared) +├── docker/ # Dockerfile, entrypoint, nginx +├── docs/ # Документация, ADR +├── specs/ # 40+ feature specifications +├── scripts/ # Утилиты (coverage, security, build) +├── research/ # Исследования (mcp-superset) +├── semantics/ # Семантическая карта кода +├── dist/ # Релизные бандлы +├── storage/ # Runtime данные (backups, repos) +├── certs/ # SSL-сертификаты +└── examples/ # Примеры интеграции +``` + +## Технологический стек + +**Backend:** Python 3.9+ (FastAPI 0.126, SQLAlchemy 2.0, APScheduler 3.11), PostgreSQL 16, Authlib, JWT, OpenAI API, GitPython, Playwright, lingua-language-detector + +**Frontend:** Svelte 5 (Runes), SvelteKit 2.49, Vite 7, Tailwind CSS 3, Vitest 4.1, Playwright 1.60 + +**Agent:** Gradio 5.50+, LangChain Core 0.3+, LangGraph 0.2+, LangGraph Checkpoint Postgres, pdfplumber, sentence-transformers (optional) + +**DevOps:** Docker & Docker Compose (3 профиля + E2E), GitHub Actions (CI), Nginx (опциональный SSL) + +## Docker (рекомендуется) + +### Профили окружения + +Система поддерживает несколько профилей через `.env` файлы: + +| Профиль | Файл | Команда | +|---|---|---| +| **current** | `.env.current` | `docker compose --profile current up --build` | +| **master** | `.env.master` | `docker compose --profile master up --build` | +| **enterprise-clean** | `.env.enterprise-clean` | `docker compose --profile enterprise-clean up --build` | +| **e2e** | `.env.e2e` | `docker compose -f docker-compose.e2e.yml up --build` | + +```bash +git clone +cd superset-tools +cp .env.example .env +docker compose --profile current up --build +``` + +После запуска: +- Frontend: http://localhost:8000 +- Backend API: http://localhost:8001 +- PostgreSQL: localhost:5432 +- Agent UI: http://localhost:8002 (gradio) + +### 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 +``` + +## Локальная разработка + +### Backend + +```bash +cd backend +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements-backend.txt +pip install -e ../shared +python3 -m uvicorn src.app:app --reload --port 8000 +``` + +### Frontend + +```bash +cd frontend +npm install +npm run dev -- --port 5173 +``` + +### Agent + +```bash +cd agent +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +pip install -e ../shared +python -m ss_tools_agent +``` + +### Начальная настройка + +```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 '' +``` + +## Конфигурация + +Полный список переменных — в каждом `.env.*.example` файле. + +### Основные категории + +| Категория | Переменные | Описание | +|---|---|---| +| **Security** | `AUTH_SECRET_KEY`, `ENCRYPTION_KEY`, `SERVICE_JWT` | JWT-подпись, шифрование данных, сервисный токен agent→backend | +| **Database** | `DATABASE_URL`, `AUTH_DATABASE_URL`, `TASKS_DATABASE_URL` | PostgreSQL подключения | +| **Admin bootstrap** | `INITIAL_ADMIN_CREATE`, `INITIAL_ADMIN_USERNAME`, `INITIAL_ADMIN_PASSWORD`, `INITIAL_ADMIN_EMAIL` | Автосоздание admin при первом запуске | +| **LLM** | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `LLM_BASE_URL`, `LLM_MODEL` | Провайдеры и модели | +| **Agent** | `AGENT_PORT`, `ENABLE_EMBEDDING_ROUTER` | Порт Gradio, семантический роутинг | +| **Features** | `FEATURES__DATASET_REVIEW`, `FEATURES__HEALTH_MONITOR` | Включение фич | +| **SSO** | `ADFS_CLIENT_ID`, `ADFS_CLIENT_SECRET`, `ADFS_METADATA_URL` | Active Directory Federation Services | +| **Certificates** | `CERTS_PATH`, `SSL_KEY_PASSPHRASE`, `LLM_CA_CERT_URLS` | PKI для корпоративных сетей | +| **CORS** | `ALLOWED_ORIGINS`, `FORCE_HTTPS`, `APP_TIMEZONE` | Безопасность и регион | +| **Logging** | `ENABLE_BELIEF_STATE_LOGGING`, `TASK_LOG_LEVEL` | Структурированное логирование | +| **Ports** | `BACKEND_HOST_PORT`, `FRONTEND_HOST_PORT`, `AGENT_HOST_PORT`, `POSTGRES_HOST_PORT` | Проброс портов Docker | + +## AI-агент + +Отдельный сервис с чат-интерфейсом для управления платформой на естественном языке: + +- **LangGraph-граф** — оркестрация multi-step диалогов с постгресовой персистентностью +- **Embedding-роутинг** — семантический выбор инструмента (опционально, требует sentence-transformers) +- **Confirmation flow** — подтверждение деструктивных операций +- **Загрузка документов** — парсинг PDF/XLSX для контекстного анализа +- **Gradio UI** — веб-интерфейс + +```bash +# Docker +docker compose --profile current up agent + +# Локально +cd agent && pip install -r requirements.txt && python -m ss_tools_agent +``` + +## Система сборки + +`build.sh` — унифицированная CLI-утилита: + +```bash +# Сборка и запуск +./build.sh compose # docker compose up --build (current profile) +./build.sh compose:master # docker compose up (master profile) + +# Индивидуальные сборки +./build.sh backend # backend image only +./build.sh frontend # frontend image only +./build.sh agent # agent image only + +# Offline-бандлы +./build.sh bundle v1.0.0 # полный бандл (все сервисы) +./build.sh bundle:light v1.0.0 # light (backend + frontend) +``` + +Артефакты: `dist/docker/superset-tools..tar.xz` + sha256sum + manifest. + +## Тестирование + +### Makefile (tiered test system) + +```bash +make test # Tier 1: быстрые unit-тесты backend + frontend (<30с) +make test-unit # Backend unit-тесты с SQLite (без Docker) +make test-frontend # Frontend vitest-тесты +make test-related F=path # Tier 2: умный выбор тестов для изменённого файла +make test-integration # Tier 3: backend integration с testcontainers +make test-e2e # Tier 3: Playwright E2E (требуется запущенное приложение) +make test-all # Все тесты (без установки зависимостей) + +make lint # Все линтеры +make lint-backend # ruff check +make lint-frontend # eslint + +make coverage # coverage обоих стеков +``` + +### Самостоятельный запуск + +```bash +# Backend тесты +cd backend && source .venv/bin/activate && pytest + +# Frontend тесты +cd frontend && npm run test + +# Agent тесты +cd agent && source .venv/bin/activate && pytest + +# Конкретный тест +pytest backend/tests/test_auth.py::test_create_user +``` + +### E2E тестирование + +```bash +docker compose -f docker-compose.e2e.yml up --build +cd frontend && npm run test:e2e +``` + +## Покрытие кода + +Сводный отчёт — `scripts/coverage-summary.sh`: + +```bash +./scripts/coverage-summary.sh # Полный запуск (integration + frontend) +./scripts/coverage-summary.sh --unit # Backend unit (SQLite) + frontend +./scripts/coverage-summary.sh --frontend-only # Только frontend +./scripts/coverage-summary.sh --backend-only --unit # Только backend +./scripts/coverage-summary.sh --output-dir ./reports/coverage +``` + +Результат: `coverage-summary/index.html`. + +### Текущие показатели + +| Стек | Тип тестов | Процент | Покрытие (Stmts) | +|---|---|---|---| +| Backend (unit) | 1723 | 1721/2 ✅ | 48% | +| Backend (integration) | 167 | 167/0 ✅ | 12% | +| Frontend | 2443 | 2442/1 ✅ | 99.25% | + +## SSL/TLS конфигурация + +### Сертификаты для HTTPS (nginx) + +Поместите файлы в `./certs/`: + +**Вариант A — отдельные файлы:** +``` +./certs/server.crt # SSL сертификат +./certs/server.key # Приватный ключ +``` + +**Вариант B — зашифрованный ключ + пароль:** +``` +./certs/server.crt # SSL сертификат +./certs/server.key # Приватный ключ (зашифрован, с DEK-Info) +SSL_KEY_PASSPHRASE=my-passphrase +``` + +**Вариант C — PKCS#12 контейнер:** +``` +./certs/server.p12 # Контейнер с сертификатом + ключом +SSL_KEY_PASSPHRASE=my-passphrase +``` + +Entrypoint автоматически извлекает `.crt` и `.key` из `.p12`, расшифровывает ключ и передаёт nginx (ключ остаётся в tmpfs контейнера). + +### Корпоративные CA-сертификаты + +Положите `.crt`/`.pem` в `./certs/` — entrypoint установит их в системное хранилище Alpine и NSS (Chromium/Playwright). Поддерживаются цепочки (Root → Intermediate). + +### LLM CA-сертификаты + +```bash +LLM_CA_CERT_URLS="http://pki.company.com/root-ca.crt http://pki.company.com/intermediate-ca.crt" +``` + +Сертификаты скачиваются на старте backend и agent контейнеров, конвертируются из DER в PEM при необходимости, устанавливаются в системное хранилище. + +### Диагностика SSL + +```bash +scripts/check_llm_certs.py # Полная проверка цепочки доверия +scripts/diag_container.py --target your-llm-provider.com:443 # Контейнерная диагностика +``` + +Подробнее — [ADR-0009](docs/adr/ADR-0009-ssl-certificate-management.md). +`LLM_SSL_VERIFY` удалён в 0.2.x — TLS verify всегда включён. + +## Enterprise Clean Deployment + +Разворот в корпоративной сети с очищенным дистрибутивом (без тестовых данных, запрет внешних источников, compliance-проверка): + +```bash +cp .env.enterprise-clean.example .env +docker compose --profile enterprise-clean up --build +``` + +Поддерживаются CLI, API и TUI flows. Подробнее — [docs/enterprise-clean.md](docs/enterprise-clean.md). + +## Авторизация + +Два метода аутентификации: + +1. **Локальная** (username/password) — JWT-токены, RBAC (admin/analyst/viewer) +2. **ADFS SSO** — Active Directory Federation Services + +Управление: `POST /api/admin/users`, `POST /api/admin/roles`. + +## Мониторинг + +- **Dashboard Hub** — управление дашбордами с Git-статусом +- **Dataset Hub** — управление датасетами с прогрессом маппинга +- **Task Drawer** — мониторинг фоновых задач (WebSocket real-time) +- **Unified Reports** — `GET /api/reports?page=1&page_size=20` (фильтры по статусу, типу, дате) +- **Health Monitor** — мониторинг здоровья системы (через `FEATURES__HEALTH_MONITOR`) +- **Semantic Map** — автоматически генерируемая семантическая карта кода (`semantics/semantic_map.json`) + +## Спецификации + +В `specs/` ведётся 40+ feature specifications. Каждая включает: `spec.md`, `research.md`, `plan.md`, `contracts/modules.md`, `data-model.md`, `checklists/requirements.md`, `tasks.md`. + +| # | Название | Описание | +|---|---|---| +| 011 | `git-integration-dashboard` | Git-интеграция дашбордов | +| 017 | `llm-analysis-plugin` | LLM-аналитика и валидация | +| 022 | `sync-id-cross-filters` | Sync ID cross-filters | +| 023 | `clean-repo-enterprise` | Чистый репозиторий для enterprise | +| 033 | `gradio-agent-chat` | Gradio/LangGraph AI-агент | +| 034 | `task-status-center` | Центр статуса задач | +| 038 | `dashboard-scenario-model` | Сценарная модель дашбордов | +| 041 | `dataset-lineage-blast-radius` | Lineage и blast radius датасетов | + +## Примеры скриптов + +Примеры интеграции с внешними системами (Airflow, CI/CD, cron) — в [`examples/`](./examples/): + +- [Python](examples/maintenance-api-python.py) +- [Bash](examples/maintenance-api-bash.sh) + +Аутентификация через API Key (`X-API-Key`), запуск и завершение maintenance-событий. + +## Утилиты + +| Скрипт | Назначение | +|---|---| +| `coverage-summary.sh` | Сводный отчёт покрытия | +| `scan_secrets.sh` | Сканирование секретов | +| `check_llm_certs.py` | Проверка SSL-сертификатов LLM | +| `diag_container.py` | SSL-диагностика | +| `find-related-tests.py` | Поиск тестов по изменённому файлу | +| `pretty_cot.py` | Форматирование CoT-логов | +| `gen_semantics.py` | Семантическая карта кода | +| `build_offline_docker_bundle.sh` | Сборка offline-бандлов | + +## Исследования + +- **mcp-superset** — MCP-сервер для Apache Superset (137 инструментов, PyPI). Streamable HTTP, SSE, stdio транспорты. Подробнее — [`research/mcp-superset/`](research/mcp-superset/). diff --git a/README.md b/README.md index ff31368b9..2ab1bab6c 100755 --- a/README.md +++ b/README.md @@ -1,369 +1,187 @@ # superset-tools -[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue?logo=python)](https://www.python.org/) -[![Node 18+](https://img.shields.io/badge/node-18+-green?logo=node.js)](https://nodejs.org/) [![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE) -[![Docker](https://img.shields.io/badge/docker-24+-blue?logo=docker)](https://www.docker.com/) -**Инструменты автоматизации для Apache Superset: миграция, версионирование, аналитика и управление данными** +**Корпоративная платформа для управления Apache Superset, перевода данных с помощью LLM и безопасной доставки аналитики между окружениями.** -## 📋 Содержание +superset-tools помогает превратить набор разрозненных дашбордов, ручных переносов и служебных скриптов в управляемый процесс: с версиями, согласованиями, аудитом, фоновым выполнением и AI-ассистентом. -- [О проекте](#-о-проекте) -- [Возможности](#-возможности) -- [Архитектура](#-архитектура) -- [Быстрый старт](#-быстрый-старт) -- [Документация](#-документация) -- [Тестирование](#-тестирование) -- [Покрытие кода](#-покрытие-кода) -- [Enterprise Clean Deployment](#-enterprise-clean-deployment) -- [Авторизация](#-авторизация) -- [Мониторинг](#-мониторинг) -- [Вклад в проект](#-вклад-в-проект) -- [Лицензия](#-лицензия) +--- -## 📖 О проекте +## Когда Superset уже вырос, а процессы вокруг него — ещё нет -superset-tools — комплексная платформа для автоматизации работы с Apache Superset, предоставляющая инструменты для LLM-перевода контента баз данных, миграции дашбордов, управления версиями через Git, LLM-аналитики и многопользовательского контроля доступа. Система построена на модульной архитектуре с плагинной системой расширений. +На старте Apache Superset обычно прост: аналитик создаёт датасет, собирает дашборд и показывает его коллегам. Но по мере роста компании появляются новые окружения, подразделения, языки, требования безопасности и сотни связанных объектов. -## ✨ Возможности +В этот момент команда сталкивается с типичными вопросами: -### 🌐 LLM-перевод контента баз данных — главная фича +- Как перенести дашборд из разработки в production и ничего не сломать? +- Как понять, кто изменил отчёт и можно ли вернуть предыдущую версию? +- Как перевести сотни тысяч наименований и описаний, сохранив отраслевую терминологию? +- Как контролировать длительные операции без постоянного просмотра логов? +- Как дать аналитикам свободу, не теряя управляемость и аудит? +- Как подключить LLM к внутренним данным, не превращая это в набор несвязанных экспериментов? -superset-tools умеет переводить данные прямо в вашей БД: сотни тысяч строк номенклатуры, спецификаций, паспортов изделий — за один прогон. Никакой ручной работы, никаких копипаст в Google Translate. +superset-tools объединяет эти задачи в одной платформе и делает работу с Superset воспроизводимой, наблюдаемой и безопасной. -Как это работает: выбираете таблицу-источник, указываете колонки, задаёте целевые языки и 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** | Полнотекстовый поиск по датасетам | +| **Быстрый выпуск многоязычной отчётности** | Массовый LLM-перевод данных с корпоративными словарями и предварительной проверкой | +| **Меньше ошибок при релизах** | Dry-run перед миграцией показывает изменения и риски до применения | +| **Прозрачная история изменений** | Дашборды и связанные объекты версионируются через Git | +| **Снижение ручной работы** | Повторяемые операции запускаются из интерфейса, по расписанию или через API | +| **Контроль длительных процессов** | Прогресс, результаты и ошибки доступны в реальном времени | +| **Управляемое использование AI** | Единые LLM-провайдеры, словари, аудит и подтверждение критических действий | +| **Готовность к корпоративной среде** | Ролевая модель, ADFS SSO, аудит и поддержка закрытых контуров | -Пишите свои плагины, подключайте через простой Python API. Никакой магии — только чёткий контракт. +## Ключевые сценарии -## 🏗️ Архитектура +### Перевод корпоративных данных без ручной обработки -### Технологический стек +Представьте каталог из 300 000 позиций: наименования продукции, технические характеристики, марки материалов и примечания. Отчётность нужно подготовить на английском, немецком и китайском языках, при этом терминология должна соответствовать внутренним стандартам компании. -**Backend:** Python 3.9+ (FastAPI, SQLAlchemy, APScheduler), PostgreSQL, GitPython, OpenAI API, Playwright +В superset-tools команда выбирает источник, нужные поля и языки, подключает терминологический словарь и сначала получает небольшую выборку для проверки. После согласования система запускает полный перевод, сохраняет результат и формирует отчёт о выполнении. -**Frontend:** SvelteKit (Svelte 5.x), Vite, Tailwind CSS, WebSocket +При следующем запуске переводятся только новые и изменившиеся записи. Уже обработанные данные и подтверждённые формулировки используются повторно, поэтому процесс становится быстрее и экономичнее. -**DevOps:** Docker & Docker Compose, PostgreSQL 16 +**Что поддерживается:** -### Модульная структура +- несколько целевых языков за один проход; +- OpenAI-совместимые модели и корпоративные LLM-шлюзы; +- отраслевые словари из CSV/TSV; +- предварительный просмотр результата; +- исправление переводов прямо в интерфейсе; +- инкрементальная обработка новых данных; +- плановые запуски по расписанию; +- статистика по строкам, ошибкам, кэшу и расходу токенов; +- массовая корректировка неконсистентных терминов. -``` -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/ # Спецификации -``` +### Безопасная миграция между dev, staging и production -## 🚀 Быстрый старт +Ручной export/import плохо масштабируется: идентификаторы отличаются, подключения к БД называются по-разному, а последствия становятся видны только после релиза. -### Требования +superset-tools сначала выполняет dry-run и показывает, какие объекты будут созданы или изменены, какие зависимости найдены и где есть риски. Только после проверки команда запускает реальную миграцию. -- **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 -cd superset-tools -docker compose up --build -``` +### Дашборды как управляемые цифровые активы -После запуска: -- Frontend: http://localhost:8000 -- Backend API: http://localhost:8001 -- PostgreSQL: localhost:5432 +Дашборд — это не просто экран с графиками. В нём зафиксированы бизнес-метрики, SQL-логика, фильтры и договорённости между подразделениями. Поэтому его изменения должны быть такими же прозрачными, как изменения программного кода. -### Локальная разработка +Git-интеграция superset-tools позволяет: -```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 +- хранить историю версий; +- сравнивать изменения; +- возвращаться к стабильному состоянию; +- разделять экспериментальную и промышленную работу по веткам; +- доставлять согласованные изменения в целевое окружение; +- генерировать понятные сообщения коммитов с помощью LLM. -# Frontend (в новом терминале) -cd frontend -npm install -npm run dev -- --port 5173 -``` +В результате команда получает единый процесс для аналитики и разработки, а ключевые отчёты перестают зависеть от памяти отдельных сотрудников. -### Начальная настройка +### AI-ассистент для повседневных операций -```bash -# Переменные окружения -cp .env.example backend/.env +Платформой можно управлять через чат на естественном языке. Пользователь формулирует задачу так, как привык обсуждать её с коллегами: -# Инициализация БД -cd backend && source .venv/bin/activate -python src/scripts/init_auth_db.py +> «Проверь дашборд производства перед публикацией» +> +> «Покажи последние изменения в отчёте по качеству» +> +> «Подготовь перенос дашборда на staging и сначала покажи риски» +> +> «Проанализируй загруженную спецификацию и найди связанные датасеты» -# Создание администратора -python src/scripts/create_admin.py --username admin --password '' -``` +AI-агент сохраняет контекст диалога, умеет работать с PDF и XLSX и запрашивает подтверждение перед критическими действиями. Это не отдельный демонстрационный чат, а дополнительный интерфейс к реальным операциям платформы. -> Полный каталог переменных окружения — в [`.env.example`](.env.example). +### Единый центр контроля -### Offline-бандл +Все длительные процессы — перевод, миграция, резервное копирование, анализ и Git-операции — выполняются как управляемые фоновые задачи. -```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) +## Кому подходит superset-tools + +### BI-командам + +Для управления большим количеством дашбордов и датасетов, выпуска изменений между окружениями и подготовки многоязычной отчётности. + +### Аналитикам данных + +Для запуска типовых операций из единого интерфейса, отслеживания результатов и работы с AI без необходимости писать служебные скрипты. + +### DevOps и платформенным инженерам + +Для воспроизводимых поставок, Git-процессов, интеграции с CI/CD, фоновых задач и развёртывания в закрытом контуре. + +### Руководителям ИТ, BI и DWH + +Для прозрачности процессов, разграничения доступа, истории изменений и снижения зависимости от ручных действий отдельных специалистов. + +### Командам локализации и управления данными + +Для массового перевода справочников и технического контента с контролем терминологии и качества результата. + +## Чем платформа отличается от набора скриптов + +Скрипт хорошо решает одну задачу один раз. Корпоративный процесс должен переживать рост объёмов, смену сотрудников, ошибки внешних систем и новые требования безопасности. + +superset-tools добавляет вокруг операций необходимый управленческий контур: + +- единый пользовательский интерфейс; +- роли и права доступа; +- предварительную проверку изменений; +- фоновые задачи и повторные попытки; +- историю и аудит; +- отчёты в едином формате; +- расписания и retention-политики; +- API для внешних систем; +- расширение через плагины. + +## Корпоративное использование + +Платформа рассчитана как на обычное Docker-развёртывание, так и на изолированные корпоративные сети. + +Поддерживаются: + +- локальная авторизация и ADFS SSO; +- роли `admin`, `analyst` и `viewer`; +- корпоративные CA-сертификаты; +- собственные LLM-шлюзы и OpenAI-совместимые API; +- развёртывание без доступа к внешним источникам; +- очищенные enterprise-дистрибутивы; +- журналирование действий и результатов операций. + +## Как устроен продукт + +Пользователь работает с единой веб-платформой, которая объединяет управление дашбордами, датасетами, миграциями, переводами, Git-репозиториями и фоновыми задачами. AI-агент предоставляет альтернативный диалоговый интерфейс, а API позволяет подключать CI/CD, Airflow, cron и внутренние корпоративные системы. + +Архитектура модульная: стандартные возможности реализованы как плагины, поэтому платформу можно расширять под собственные источники данных и бизнес-процессы. + +## Быстрый старт + +Инструкции по Docker-развёртыванию, локальной разработке, настройке LLM, SSO, сертификатов и закрытого контура находятся в [INSTALL.md](INSTALL.md). + +## Документация + +- [Установка и настройка](INSTALL.md) - [Архитектура системы](docs/architecture.md) -- [Архитектурные решения (ADR)](docs/adr/README.md) -- [API документация](http://localhost:8001/docs) -- [Настройка окружений](docs/settings.md) +- [Архитектурные решения](docs/adr/README.md) +- [Enterprise Clean Deployment](docs/enterprise-clean.md) +- [API после запуска](http://localhost:8001/docs) +- [Руководство для контрибьюторов](CONTRIBUTING.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 по каждому стеку открываются из сводного отчёта по ссылкам. - -## 🔐 SSL/TLS конфигурация - -### Сертификаты для HTTPS (nginx) - -Для включения HTTPS поместите файлы сертификатов в директорию `./certs/`: - -**Вариант A — отдельные файлы (без пароля):** -``` -./certs/server.crt # SSL сертификат -./certs/server.key # Приватный ключ (незашифрованный) -``` - -**Вариант B — зашифрованный ключ + пароль:** -``` -./certs/server.crt # SSL сертификат -./certs/server.key # Приватный ключ (зашифрован, с DEK-Info) -SSL_KEY_PASSPHRASE=my-passphrase # переменная окружения для расшифровки -``` - -**Вариант C — PKCS#12 контейнер:** -``` -./certs/server.p12 # Контейнер с сертификатом + ключом -SSL_KEY_PASSPHRASE=my-passphrase # пароль от контейнера -``` - -Entrypoint автоматически: -1. Извлечёт `.crt` и `.key` из `.p12` (если нет отдельных файлов) -2. Расшифрует приватный ключ через `openssl rsa` (если есть `SSL_KEY_PASSPHRASE`) -3. Передаст расшифрованный ключ nginx (ключ остаётся в tmpfs контейнера) - -> **Безопасность:** Расшифрованный ключ хранится только в tmpfs `/etc/nginx/ssl/` внутри контейнера и не пишется на диск хоста. Пароль задаётся через переменную окружения, а не через файл на volume. - -### Корпоративные CA-сертификаты - -Положите `.crt`/`.pem` файлы в `./certs/` — entrypoint установит их в системное хранилище Alpine и NSS (Chromium/Playwright). Поддерживаются цепочки из нескольких CA (Root → Intermediate). - -### LLM CA-сертификаты - -Если LLM-провайдер или Superset используют корпоративный PKI — укажите HTTP URL для скачивания CA-сертификатов: -```bash -LLM_CA_CERT_URLS="http://pki.company.com/root-ca.crt http://pki.company.com/intermediate-ca.crt" -``` -Сертификаты скачиваются на старте backend и agent контейнеров (через `certs.sh:download_llm_ca_certs()`), конвертируются из DER в PEM при необходимости, и устанавливаются в системное хранилище. - -Дополнительные сертификаты можно разместить в `CERTS_PATH=./certs` (volume mount). - -### Диагностика SSL - -```bash -# Полная проверка цепочки доверия -scripts/check_llm_certs.py - -# Контейнерная диагностика -scripts/diag_container.py --target your-llm-provider.com:443 -``` - -Подробнее — в [ADR-0009](docs/adr/ADR-0009-ssl-certificate-management.md). -`LLM_SSL_VERIFY` удалён в 0.2.x — TLS verify всегда включён. - -## 🏢 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).