diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..dcba0402 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,32 @@ +# Contributing to ss-tools + +Спасибо за интерес к проекту! Мы принимаем contributions через pull request. + +## Как помочь + +- **Сообщить об ошибке** — создайте [issue](https://github.com/anomalyco/ss-tools/issues/new) +- **Предложить идею** — создайте issue с меткой `enhancement` +- **Исправить баг** — форкните репозиторий, сделайте PR + +## Процесс + +1. Форкните репозиторий +2. Создайте ветку: `git checkout -b feature/your-feature` +3. Внесите изменения +4. Убедитесь, что тесты проходят: + ```bash + cd backend && pytest + cd frontend && npm run test + ``` +5. Сделайте коммит и push +6. Откройте Pull Request + +## Code Style + +- **Python**: PEP 8, используйте `black` + `ruff` +- **Svelte**: Svelte 5 Runes, Tailwind CSS +- **Коммиты**: пишите на русском или английском, описывайте суть изменений + +## Лицензия + +Внося contribution, вы соглашаетесь, что ваш код будет распространяться под [MIT License](LICENSE). diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..87dfb3dc --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 ss-tools + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index c51a619a..db7a4dad 100755 --- a/README.md +++ b/README.md @@ -1,67 +1,118 @@ # ss-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: миграция, версионирование, аналитика и управление данными** -## 📋 О проекте +## 📋 Содержание -ss-tools — это комплексная платформа для автоматизации работы с Apache Superset, предоставляющая инструменты для миграции дашбордов, управления версиями через Git, LLM-анализа данных и многопользовательского контроля доступа. Система построена на модульной архитектуре с плагинной системой расширений. +- [О проекте](#-о-проекте) +- [Возможности](#-возможности) +- [Архитектура](#-архитектура) +- [Быстрый старт](#-быстрый-старт) +- [Документация](#-документация) +- [Тестирование](#-тестирование) +- [Enterprise Clean Deployment](#-enterprise-clean-deployment) +- [Авторизация](#-авторизация) +- [Мониторинг](#-мониторинг) +- [Вклад в проект](#-вклад-в-проект) +- [Лицензия](#-лицензия) -### 🎯 Ключевые возможности +## 📖 О проекте -#### 🔄 Миграция данных -- **Миграция дашбордов и датасетов** между окружениями (dev/staging/prod) -- **Dry-run режим** с детальным анализом рисков и предпросмотром изменений -- **Автоматическое маппинг** баз данных и ресурсов между окружениями -- **Поддержка legacy-данных** с миграцией из SQLite в PostgreSQL +ss-tools — комплексная платформа для автоматизации работы с Apache Superset, предоставляющая инструменты для LLM-перевода контента баз данных, миграции дашбордов, управления версиями через Git, LLM-аналитики и многопользовательского контроля доступа. Система построена на модульной архитектуре с плагинной системой расширений. -#### 🌿 Git-интеграция -- **Версионирование** дашбордов через Git-репозитории -- **Управление ветками** и коммитами с помощью LLM -- **Деплой** дашбордов из Git в целевые окружения -- **История изменений** с детальным diff +## ✨ Возможности -#### 🤖 LLM-аналитика -- **Автоматическая валидация** дашбордов с помощью ИИ -- **Генерация документации** для датасетов -- **Assistant API** для natural language команд -- **Интеллектуальное коммитинг** с подсказками сообщений +### 🌐 LLM-перевод контента баз данных — главная фича -#### 📊 Управление и мониторинг -- **Многопользовательская авторизация** (RBAC) -- **Фоновые задачи** с реальным логированием через WebSocket -- **Унифицированные отчеты** по выполненным задачам -- **Хранение артефактов** с политиками retention -- **Аудит логирование** всех действий +ss-tools умеет переводить данные прямо в вашей БД: сотни тысяч строк номенклатуры, спецификаций, паспортов изделий — за один прогон. Никакой ручной работы, никаких копипаст в Google Translate. -#### 🔌 Плагины -- **MigrationPlugin** — миграция дашбордов -- **BackupPlugin** — резервное копирование -- **GitPlugin** — управление версиями -- **LLMAnalysisPlugin** — аналитика и документация -- **MapperPlugin** — маппинг колонок -- **DebugPlugin** — диагностика системы -- **SearchPlugin** — поиск по датасетам +Как это работает: выбираете таблицу-источник, указываете колонки, задаёте целевые языки и LLM-провайдера. ss-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-воркфлоу** — перед полноценным прогоном ss-tools показывает сэмпл перевода. Вы просматриваете строки, правите неудачные варианты, подтверждаете — и только потом запускаете полный прогон. +- **Словари терминологии** — загрузите CSV/TSV с правильными переводами ваших доменных терминов: «плавка → melt», «сортопрокат → bar stock», «ТУ → technical specifications». Словари автоматически подмешиваются в промпт, LLM использует именно вашу терминологию. +- **Inline-коррекция** — увидели плохой перевод в результатах? Правите прямо в UI, исправление улетает обратно в словарь. Каждый прогон делает систему умнее. +- **Инкрементальный перевод** — повторный прогон переводит только новые и изменившиеся строки (сравнение по хешу ключа). Уже переведённое не трогается. +- **Автоопределение языка источника** — не нужно указывать, на каком языке исходные данные. ss-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 — рутинная операция, которая обычно отнимает часы и чревата ошибками. ss-tools делает её предсказуемой: + +- **Dry-run режим** — перед реальными изменениями вы получаете детальный отчёт: какие объекты будут затронуты, какие риски обнаружены, что изменится в целевой среде. Никаких сюрпризов. +- **Автоматический маппинг БД** — базы данных, ресурсы и идентификаторы сопоставляются между окружениями автоматически. Никакого ручного поиска и замены. +- **Миграция legacy-данных** — встроенная поддержка переноса из SQLite в PostgreSQL. Устаревшие хранилища не помеха. + +### 🌿 Git-интеграция: дашборды как код + +Хватит копировать дашборды через export/import. Включите их в свой Git-процесс: + +- **Версионирование** — каждый дашборд — это файл в репозитории. Полная история изменений, откат на любую версию, diff любой сложности. +- **LLM-управление ветками** — создавайте ветки, коммитьте и сливайте изменения через natural language команды. «Создай ветку для эксперимента с отчётом по энергопотреблению и закоммить текущие дашборды». +- **Деплой из Git** — push в целевую ветку автоматически применяет изменения на нужном окружении. CI/CD для дашбордов. +- **Интеллектуальные сообщения коммитов** — LLM анализирует изменения и сам предлагает осмысленный заголовок коммита. + +### 🤖 LLM-аналитика: ИИ присматривает за дашбордами + +Не просто инструмент, а ваш ассистент по данным: + +- **Автовалидация дашбордов** — LLM проверяет корректность метрик, источников данных и визуализаций. Нашёл подозрительный SQL в фильтре? Сообщит до того, как дашборд попадёт к пользователям. +- **Генерация документации** — для любого датасета создаётся человекочитаемое описание: какие поля, откуда данные, какие есть зависимости. +- **Assistant API** — управляйте ss-tools голосом или текстом на естественном языке. «Перенеси дашборд производства на staging», «Покажи историю изменений по датасету качества продукции». +- **Умный коммитинг** — LLM анализирует изменения и генерирует сообщение коммита, отражающее суть. Никаких «fix» и «update». + +### 📊 Управление и мониторинг: полный контроль + +Одна консоль, чтобы править всеми: + +- **RBAC** — гибкая ролевая модель: admin, analyst, viewer. Каждый видит и делает только то, что ему разрешено. +- **Фоновые задачи с WebSocket** — запустили миграцию на час? Откройте Task Drawer и наблюдайте прогресс в реальном времени. Никаких логов, к которым нужно подключаться по SSH. +- **Unified Reports** — единый формат отчётов для всех типов задач. Один эндпоинт — любые данные. +- **Аудит** — каждое действие логируется. Кто, когда и что сделал — всегда можно выяснить. +- **Retention-политики** — артефакты автоматически очищаются по расписанию. Диски не забиваются. + +### 🔌 Плагинная архитектура: расширяйте без границ + +ss-tools спроектирован как платформа. Хотите свою логику миграции? Свой источник данных? Свой триггер? + +Каждый модуль — это изолированный плагин: + +| Плагин | Назначение | +|---|---| +| **TranslatePlugin** | LLM-перевод контента БД | +| **MigrationPlugin** | Миграция дашбордов между окружениями | +| **BackupPlugin** | Резервное копирование и восстановление | +| **GitPlugin** | Полный цикл Git-операций | +| **LLMAnalysisPlugin** | AI-валидация и генерация документации | +| **MapperPlugin** | Маппинг колонок и ресурсов | +| **DebugPlugin** | Диагностика и профилирование системы | +| **SearchPlugin** | Полнотекстовый поиск по датасетам | + +Пишите свои плагины, подключайте через простой Python API. Никакой магии — только чёткий контракт. ## 🏗️ Архитектура ### Технологический стек -**Backend:** -- Python 3.9+ (FastAPI, SQLAlchemy, APScheduler) -- PostgreSQL (основная БД) -- GitPython для Git-операций -- OpenAI API для LLM-функций -- Playwright для скриншотов +**Backend:** Python 3.9+ (FastAPI, SQLAlchemy, APScheduler), PostgreSQL, GitPython, OpenAI API, Playwright -**Frontend:** -- SvelteKit (Svelte 5.x) -- Vite -- Tailwind CSS -- WebSocket для реального логирования +**Frontend:** SvelteKit (Svelte 5.x), Vite, Tailwind CSS, WebSocket -**DevOps:** -- Docker & Docker Compose -- PostgreSQL 16 +**DevOps:** Docker & Docker Compose, PostgreSQL 16 ### Модульная структура @@ -69,24 +120,24 @@ ss-tools — это комплексная платформа для автом ss-tools/ ├── backend/ # Backend API │ ├── src/ -│ │ ├── api/ # API маршруты -│ │ ├── core/ # Ядро системы -│ │ │ ├── task_manager/ # Управление задачами -│ │ │ ├── auth/ # Авторизация -│ │ │ ├── migration/ # Миграция данных -│ │ │ └── plugins/ # Плагины -│ │ ├── models/ # Модели данных -│ │ ├── services/ # Бизнес-логика -│ │ └── schemas/ # Pydantic схемы -│ └── tests/ # Тесты +│ │ ├── api/ # API маршруты +│ │ ├── core/ # Ядро системы +│ │ │ ├── task_manager/ # Управление задачами +│ │ │ ├── auth/ # Авторизация +│ │ │ ├── migration/ # Миграция данных +│ │ │ └── plugins/ # Плагины +│ │ ├── models/ # Модели данных +│ │ ├── services/ # Бизнес-логика +│ │ └── schemas/ # Pydantic схемы +│ └── tests/ ├── frontend/ # SvelteKit приложение │ ├── src/ -│ │ ├── routes/ # Страницы +│ │ ├── routes/ # Страницы │ │ ├── lib/ -│ │ │ ├── components/ # UI компоненты -│ │ │ ├── stores/ # Svelte stores -│ │ │ └── api/ # API клиент -│ │ └── i18n/ # Мультиязычность +│ │ │ ├── components/ # UI компоненты +│ │ │ ├── stores/ # Svelte stores +│ │ │ └── api/ # API клиент +│ │ └── i18n/ # Мультиязычность │ └── tests/ ├── docker/ # Docker конфигурация ├── docs/ # Документация @@ -97,63 +148,23 @@ ss-tools/ ### Требования -**Локальная разработка:** -- Python 3.9+ -- Node.js 18+ -- npm -- 2 GB RAM (минимум) -- 5 GB свободного места +- **Docker (рекомендуется):** Docker Engine 24+, Docker Compose v2, 4 GB RAM +- **Локальная разработка:** Python 3.9+, Node.js 18+, npm, 2 GB RAM, 5 GB диска -**Docker (рекомендуется):** -- Docker Engine 24+ -- Docker Compose v2 -- 4 GB RAM (для стабильной работы) - -### Быстрое развертывание бандла (offline) +### Docker (рекомендуется) ```bash -# 1. Загрузить образ из бандла -xz -dc dist/docker/ss-tools.20260517.tar.xz | docker load - -# 2. Подготовить пароль для PostgreSQL -export POSTGRES_PASSWORD="my-strong-password" - -# 3. Запустить -docker compose -f dist/docker/docker-compose.light.yml up -d - -# 4. Создать администратора (первый запуск) -docker exec -it ss-tools-app-1 python src/scripts/create_admin.py \ - --username admin --password '' -``` - -Команды для сборки бандла: -```bash -# Легковесный all-in-one (~104 MB) -./build.sh bundle:light v1.0.0 - -# Полный релиз (backend + frontend + postgres) -./build.sh bundle v1.0.0 -``` - -### Установка и запуск - -#### Вариант 1: Docker (рекомендуется) - -```bash -# Клонирование репозитория git clone cd ss-tools - -# Запуск всех сервисов docker compose up --build - -# После запуска: -# Frontend: http://localhost:8000 -# Backend API: http://localhost:8001 -# PostgreSQL: localhost:5432 ``` -#### Вариант 2: Локально +После запуска: +- Frontend: http://localhost:8000 +- Backend API: http://localhost:8001 +- PostgreSQL: localhost:5432 + +### Локальная разработка ```bash # Backend @@ -169,186 +180,37 @@ npm install npm run dev -- --port 5173 ``` -### Первичная настройка +### Начальная настройка ```bash -# Скопируйте шаблон переменных окружения -cp .env.example backend/.env.bak # или используйте backend/.env напрямую +# Переменные окружения +cp .env.example backend/.env # Инициализация БД -cd backend -source .venv/bin/activate +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 '' +python src/scripts/create_admin.py --username admin --password '' ``` -> Полный каталог переменных окружения — в [`.env.example`](.env.example) в корне проекта. +> Полный каталог переменных окружения — в [`.env.example`](.env.example). -## 🏢 Enterprise Clean Deployment (internal-only) - -Для разворота в корпоративной сети используйте профиль enterprise clean: - -- очищенный дистрибутив без test/demo/load-test данных; -- запрет внешних интернет-источников; -- загрузка ресурсов только с внутренних серверов компании; -- обязательная блокирующая проверка clean/compliance перед выпуском. - -### Операционный workflow (CLI/API/TUI) - -#### 1) Headless flow через CLI (рекомендуется для CI/CD) +### Offline-бандл ```bash -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 +# Загрузка образа +xz -dc dist/docker/ss-tools.20260517.tar.xz | docker load +export POSTGRES_PASSWORD="my-strong-password" +docker compose -f dist/docker/docker-compose.light.yml up -d ``` -#### 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) - -```bash -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 для такого релиза: - -```bash -# 1. Собрать образы в подключённом контуре -./build.sh bundle v1.0.0-rc2-docker - -# Результат: dist/docker/ -# backend.v1.0.0-rc2-docker.tar.xz -# frontend.v1.0.0-rc2-docker.tar.xz -# postgres.v1.0.0-rc2-docker.tar.xz -# manifest + sha256sums + docker-compose.enterprise-clean.yml + .env.enterprise-clean.example - -# 2. Передать dist/docker/* в изолированный контур -# 3. Импортировать образы локально (распаковка на лету) -xz -dc dist/docker/backend.v1.0.0-rc2-docker.tar.xz | docker load -xz -dc dist/docker/frontend.v1.0.0-rc2-docker.tar.xz | docker load -xz -dc dist/docker/postgres.v1.0.0-rc2-docker.tar.xz | docker load - -# 4. Подготовить env из шаблона -cp dist/docker/.env.enterprise-clean.example .env.enterprise-clean - -# 4a. Для первого запуска задать bootstrap администратора -# INITIAL_ADMIN_CREATE=true -# INITIAL_ADMIN_USERNAME= -# INITIAL_ADMIN_PASSWORD= - -# 5. Запустить только локальные образы -docker compose --env-file .env.enterprise-clean -f dist/docker/docker-compose.enterprise-clean.yml up -d -``` - -Для легковесного all-in-one образа (без Playwright, **~104 MB** вместо 575 MB): - -```bash -# Сборка -./build.sh bundle:light v1.0.0 - -# Результат: -# dist/docker/ss-tools.v1.0.0.tar.xz (×5.5 меньше за счёт xz -9) -# dist/docker/docker-compose.light.yml -# dist/docker/manifest-light.v1.0.0.txt -# dist/docker/sha256sums-light.v1.0.0.txt - -# Загрузка и запуск: -xz -dc dist/docker/ss-tools.v1.0.0.tar.xz | docker load -docker compose -f dist/docker/docker-compose.light.yml up -``` - -Bootstrap администратора выполняется entrypoint-скриптом внутри backend container: -- если `INITIAL_ADMIN_CREATE=true`, контейнер вызывает [`create_admin.py`](backend/src/scripts/create_admin.py) перед стартом API; -- если администратор уже существует, учётная запись не меняется; -- теги в [`.env.enterprise-clean.example`](.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 добавлены; -- unified `build.sh bundle ` добавлен для `build -> save -> checksum` (заменил `scripts/build_offline_docker_bundle.sh`); -- следующим шагом стоит включить docker image digests в clean-release manifest; -- следующим шагом стоит добавить smoke-check, что compose-файлы не содержат внешних registry references вне allowlist. +Сборка бандла: `./build.sh bundle:light v1.0.0` (light, ~104 MB) или `./build.sh bundle v1.0.0` (full). ## 📖 Документация - [Установка и настройка](docs/installation.md) - [Архитектура системы](docs/architecture.md) -- [Разработка плагинов](docs/plugin_dev.md) - [API документация](http://localhost:8001/docs) - [Настройка окружений](docs/settings.md) @@ -356,94 +218,52 @@ Bootstrap администратора выполняется entrypoint-скр ```bash # Backend тесты -cd backend -source .venv/bin/activate -pytest +cd backend && source .venv/bin/activate && pytest # Frontend тесты -cd frontend -npm run test +cd frontend && npm run test -# Запуск конкретного теста +# Конкретный тест pytest tests/test_auth.py::test_create_user ``` +## 🏢 Enterprise Clean Deployment +Для разворота в корпоративной сети с очищенным дистрибутивом (без тестовых данных, с запретом внешних источников и обязательной compliance-проверкой) используется профиль **enterprise clean**. + +Поддерживаются CLI, API и TUI flows. Подробная документация — в [docs/enterprise-clean.md](docs/enterprise-clean.md). ## 🔐 Авторизация Система поддерживает два метода аутентификации: -1. **Локальная аутентификация** (username/password) +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"] -} -``` +Управление пользователями и ролями — через `POST /api/admin/users` и `POST /api/admin/roles`. Документация — `docs/installation.md`. ## 📊 Мониторинг -### Отчеты о задачах - -```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 -``` +API: `GET /api/reports?page=1&page_size=20` (фильтры по статусу, типу, дате). ## 💻 Примеры скриптов -Примеры Python и Bash скриптов для вызова API ss-tools из внешних систем (Airflow, CI/CD, cron) находятся в каталоге [`examples/`](./examples/). +Примеры интеграции с внешними системами (Airflow, CI/CD, cron) — в [`examples/`](./examples/): -- **Python** — [`examples/maintenance-api-python.py`](./examples/maintenance-api-python.py) -- **Bash** — [`examples/maintenance-api-bash.sh`](./examples/maintenance-api-bash.sh) +- [Python](examples/maintenance-api-python.py) +- [Bash](examples/maintenance-api-bash.sh) -Скрипты демонстрируют аутентификацию через API Key (`X-API-Key`), запуск и завершение maintenance-событий, а также обработку ошибок. +Скрипты демонстрируют аутентификацию через API Key (`X-API-Key`), запуск и завершение maintenance-событий, обработку ошибок. + +## 🤝 Вклад в проект + +Мы приветствуем contributions! См. [CONTRIBUTING.md](CONTRIBUTING.md). + +## 📄 Лицензия + +Проект распространяется под лицензией [MIT](LICENSE). diff --git a/docs/enterprise-clean.md b/docs/enterprise-clean.md new file mode 100644 index 00000000..5bedc124 --- /dev/null +++ b/docs/enterprise-clean.md @@ -0,0 +1,155 @@ +# Enterprise Clean Deployment (internal-only) + +Для разворота в корпоративной сети используйте профиль enterprise clean: + +- очищенный дистрибутив без test/demo/load-test данных; +- запрет внешних интернет-источников; +- загрузка ресурсов только с внутренних серверов компании; +- обязательная блокирующая проверка clean/compliance перед выпуском. + +## Операционный workflow (CLI/API/TUI) + +### 1) Headless flow через CLI (рекомендуется для CI/CD) + +```bash +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) + +```bash +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 для такого релиза: + +```bash +# 1. Собрать образы в подключённом контуре +./build.sh bundle v1.0.0-rc2-docker + +# Результат: dist/docker/ +# backend.v1.0.0-rc2-docker.tar.xz +# frontend.v1.0.0-rc2-docker.tar.xz +# postgres.v1.0.0-rc2-docker.tar.xz +# manifest + sha256sums + docker-compose.enterprise-clean.yml + .env.enterprise-clean.example + +# 2. Передать dist/docker/* в изолированный контур +# 3. Импортировать образы локально (распаковка на лету) +xz -dc dist/docker/backend.v1.0.0-rc2-docker.tar.xz | docker load +xz -dc dist/docker/frontend.v1.0.0-rc2-docker.tar.xz | docker load +xz -dc dist/docker/postgres.v1.0.0-rc2-docker.tar.xz | docker load + +# 4. Подготовить env из шаблона +cp dist/docker/.env.enterprise-clean.example .env.enterprise-clean + +# 4a. Для первого запуска задать bootstrap администратора +# INITIAL_ADMIN_CREATE=true +# INITIAL_ADMIN_USERNAME= +# INITIAL_ADMIN_PASSWORD= + +# 5. Запустить только локальные образы +docker compose --env-file .env.enterprise-clean -f dist/docker/docker-compose.enterprise-clean.yml up -d +``` + +Для легковесного all-in-one образа (без Playwright, **~104 MB** вместо 575 MB): + +```bash +# Сборка +./build.sh bundle:light v1.0.0 + +# Результат: +# dist/docker/ss-tools.v1.0.0.tar.xz (×5.5 меньше за счёт xz -9) +# dist/docker/docker-compose.light.yml +# dist/docker/manifest-light.v1.0.0.txt +# dist/docker/sha256sums-light.v1.0.0.txt + +# Загрузка и запуск: +xz -dc dist/docker/ss-tools.v1.0.0.tar.xz | docker load +docker compose -f dist/docker/docker-compose.light.yml up +``` + +Bootstrap администратора выполняется entrypoint-скриптом внутри backend container: +- если `INITIAL_ADMIN_CREATE=true`, контейнер вызывает [`create_admin.py`](backend/src/scripts/create_admin.py) перед стартом API; +- если администратор уже существует, учётная запись не меняется; +- теги в [`.env.enterprise-clean.example`](.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 добавлены; +- unified `build.sh bundle ` добавлен для `build -> save -> checksum` (заменил `scripts/build_offline_docker_bundle.sh`); +- следующим шагом стоит включить docker image digests в clean-release manifest; +- следующим шагом стоит добавить smoke-check, что compose-файлы не содержат внешних registry references вне allowlist.