# Установка и настройка ss-tools

Эта документация описывает процесс установки и настройки ss-tools для локальной разработки и продакшн-среды.

## Содержание

- [Требования](#требования)
- [Установка через Docker](#установка-через-docker)
- [Локальная установка](#локальная-установка)
- [Первая настройка](#первая-настройка)
- [Конфигурация окружений](#конфигурация-окружений)
- [Troubleshooting](#troubleshooting)

## Требования

### Минимальные требования для локальной разработки

- **Python**: 3.9 или новее
- **Node.js**: 18 или новее
- **npm**: 9 или новее
- **RAM**: 4 GB
- **Диск**: 5 GB свободного места
- **Операционная система**: Linux, macOS или WSL2

### Рекомендуемые требования для продакшн

- **Docker Engine**: 24 или новее
- **Docker Compose**: v2.3 или новее
- **RAM**: 8 GB
- **Диск**: 15+ GB свободного места
- **PostgreSQL**: 16 (через Docker)

### Дополнительные зависимости

Для локальной разработки могут потребоваться:

- **Git**: для клонирования репозитория
- **Curl**: для тестирования API
- **Python-разработчик**: для компиляции некоторых Python пакетов

## Установка через Docker

### 1. Клонирование репозитория

```bash
git clone <repository-url>
cd ss-tools
```

### 2. Настройка переменных окружения

Создайте файл `.env` в корневой директории:

```bash
# Backend и Frontend порты
BACKEND_PORT=8000
FRONTEND_PORT=5173

# PostgreSQL порт
POSTGRES_HOST_PORT=5432

# Альтернативные образы PostgreSQL (если есть проблемы с основным)
POSTGRES_IMAGE=postgres:16-alpine

# Порты для Docker контейнеров
BACKEND_HOST_PORT=8001
FRONTEND_HOST_PORT=8000
```

### 3. Запуск контейнеров

```bash
# Сборка и запуск всех сервисов
docker compose up --build

# Запуск в фоне с логами
docker compose up -d

# Мониторинг логов
docker compose logs -f
```

### 4. Проверка установки

После запуска проверьте доступность сервисов:

```bash
# Frontend
curl http://localhost:8000

# Backend API
curl http://localhost:8001/docs

# PostgreSQL
docker exec ss_tools_db pg_isready -U postgres
```

## Локальная установка

### 1. Backend установка

```bash
cd backend

# Создание виртуального окружения
python3 -m venv .venv

# Активация виртуального окружения
source .venv/bin/activate  # На Linux/macOS
# или
.venv\Scripts\activate  # На Windows

# Установка зависимостей
pip install -r requirements.txt

# Запуск backend
python3 -m uvicorn src.app:app --reload --port 8000
```

### 2. Frontend установка

Откройте новый терминал:

```bash
cd frontend

# Установка зависимостей
npm install

# Запуск dev сервера
npm run dev -- --port 5173
```

### 3. Настройка PostgreSQL

Для локальной разработки можно использовать встроенную PostgreSQL или подключиться к существующей:

```bash
# Создание БД (если не создана через Docker)
createdb ss_tools

# Или подключение к существующей
psql -U postgres -d ss_tools
```

## Первая настройка

### 1. Инициализация базы данных

```bash
cd backend
source .venv/bin/activate

# Создание таблиц
python src/scripts/init_auth_db.py
```

### 2. Создание администратора

```bash
python src/scripts/create_admin.py --username admin --password admin
```

**Важно**: После создания администратора измените пароль в продакшн-среде!

### 3. Настройка окружений

Перейдите в админ-панель (http://localhost:8000/settings) и добавьте свои Superset окружения:

- **Source Environment**: окружение для миграции данных
- **Target Environment**: целевое окружение
- **Superset URL**: базовый URL Superset (например, https://superset.example.com)
- **API URL**: URL API Superset (обычно /api/v1)
- **Auth Type**: Basic Auth или OAuth2

### 4. Настройка Git-конфигураций

Если планируете использовать Git-интеграцию:

1. Перейдите в **Settings → Git**
2. Добавьте конфигурацию Git-сервера:
   - **Name**: идентификатор (например, "GitHub Production")
   - **Type**: GitHub, GitLab или Bitbucket
   - **URL**: URL репозитория
   - **Username**: имя пользователя
   - **Personal Access Token**: токен с правами на репозитории

### 5. Настройка LLM-провайдеров

Для LLM-аналитики и документации:

1. Перейдите в **Settings → LLM**
2. Добавьте провайдера:
   - **Name**: идентификатор (например, "OpenAI Production")
   - **Provider**: OpenAI, Anthropic и т.д.
   - **API Key**: ключ API (будет зашифрован)
   - **Model**: используемая модель (например, gpt-4-turbo)
   - **Binding**: для каких задач использовать (validation, docs, commit)

## Конфигурация окружений

### Структура конфигурации

Конфигурация хранится в PostgreSQL в таблице `app_configurations`:

```sql
SELECT * FROM app_configurations WHERE key = 'global_settings';
```

### Основные настройки

```json
{
  "global_settings": {
    "enable_belief_state_logging": true,
    "task_log_level": "INFO",
    "retention_period_days": 30,
    "storage_path": "/app/storage",
    "git_repos_path": "/app/backend/git_repos"
  },
  "environments": [
    {
      "id": "dev",
      "name": "Development",
      "superset_url": "http://localhost:8088",
      "api_url": "/api/v1",
      "auth_type": "basic",
      "username": "admin",
      "password": "password"
    },
    {
      "id": "staging",
      "name": "Staging",
      "superset_url": "https://staging.superset.example.com",
      "api_url": "/api/v1",
      "auth_type": "oauth2",
      "oauth_url": "https://sso.example.com/oauth2/authorize",
      "token_url": "https://sso.example.com/oauth2/token"
    }
  ]
}
```

### Переменные окружения

Основные переменные окружения:

```bash
# Database
DATABASE_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools
TASKS_DATABASE_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools
AUTH_DATABASE_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools

# Server
BACKEND_PORT=8000
FRONTEND_PORT=5173

# Security
SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=1440

# LLM (опционально)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Git (опционально)
GIT_USERNAME=your-git-username
GIT_EMAIL=your-email@example.com
```

### Включение/отключение функций

```bash
# Включение belief state логирования
export ENABLE_BELIEF_STATE_LOGGING=true

# Уровень логирования задач
export TASK_LOG_LEVEL=DEBUG

# Период retention (в днях)
export RETENTION_PERIOD_DAYS=90
```

## Enterprise Clean Release (изолированный контур)

### Назначение

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

### Операторский цикл (TUI)

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

Ожидаемый flow:
1. Выбрать `candidate_id`.
2. Подтвердить `profile=enterprise-clean`.
3. Запустить проверку (F5).
4. Дождаться терминального статуса:
   - `COMPLIANT` — кандидат готов к следующему этапу выпуска;
   - `BLOCKED` — выпуск запрещён до устранения нарушений.

### Политика источников (internal-only)

Разрешены только хосты из внутреннего реестра компании, например:
- `repo.intra.company.local`
- `artifacts.intra.company.local`
- `pypi.intra.company.local`

Любой внешний endpoint (например `pypi.org`) трактуется как `external-source` и блокирует выпуск.

### Recovery при BLOCKED

1. Открыть детали нарушений (категория, location, remediation).
2. Удалить запрещённые данные или заменить внешний источник на внутренний.
3. Повторить запуск проверки (F5) до статуса `COMPLIANT`.

### Обязательный CI gate

После операторского TUI-прогона тот же профиль должен пройти в CI.
Только `COMPLIANT` в CI допускает релиз в корпоративный контур.

## Troubleshooting

### Проблемы с Docker

**Проблема**: Контейнеры не запускаются

```bash
# Проверка статуса
docker compose ps

# Просмотр логов
docker compose logs backend
docker compose logs frontend

# Очистка и пересборка
docker compose down -v
docker compose up --build
```

**Проблема**: PostgreSQL порт занят

```bash
# Изменение порта в .env
POSTGRES_HOST_PORT=5433

# Перезапуск
docker compose down
docker compose up -d
```

### Проблемы с Python

**Проблема**: ImportError при импорте модулей

```bash
# Проверка Python версии
python3 --version  # Должен быть 3.9+

# Пересоздание виртуального окружения
cd backend
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt --upgrade
```

**Проблема**: Нет прав на создание файлов

```bash
# На Linux/macOS
chmod +x run.sh
chmod +x build.sh

# На Windows
# Права обычно не требуются для .sh скриптов
```

### Проблемы с Node.js

**Проблема**: npm не устанавливает зависимости

```bash
# Очистка кэша npm
npm cache clean --force

# Пересоздание node_modules
cd frontend
rm -rf node_modules package-lock.json
npm install
```

### Проблемы с БД

**Проблема**: Подключение к PostgreSQL не удается

```bash
# Проверка доступности БД
docker exec ss_tools_db pg_isready -U postgres

# Проверка таблиц
docker exec ss_tools_db psql -U postgres -d ss_tools -c "\dt"

# Ручная инициализация
docker exec -it ss_tools_db psql -U postgres -d ss_tools
```

**Проблема**: Сломанные миграции

```bash
# Откат последней миграции
cd backend
source .venv/bin/activate
alembic downgrade -1

# Повторная инициализация
python src/scripts/init_auth_db.py
```

### Проблемы с Git-интеграцией

**Проблема**: Не удается инициализировать репозиторий

```bash
# Проверка прав на директорию
ls -la backend/git_repos/

# Создание директории вручную
mkdir -p backend/git_repos/
chmod 755 backend/git_repos/

# Проверка Git конфигураций
git config --global user.name
git config --global user.email
```

**Проблема**: Нет доступа к репозиторию

```bash
# Проверка токена
# Токен должен иметь права на:
# - Push
# - Pull
# - Create branches
# - Delete branches (если нужно)
```

## Проверка установки

### Тестирование API

```bash
# Тестирование health endpoint
curl http://localhost:8001/health

# Тестирование списка плагинов
curl http://localhost:8001/api/plugins

# Тестовая аутентификация
curl -X POST http://localhost:8001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}'
```

### Тестирование фронтенда

1. Откройте браузер на http://localhost:8000
2. Проверьте, что вы можете войти с учетными данными администратора
3. Проверьте доступность основных разделов:
   - Dashboard Hub
   - Dataset Hub
   - Settings
   - Reports

## Дополнительные ресурсы

- [Архитектура системы](architecture.md)
- [Настройка окружений](settings.md)
- [Разработка плагинов](plugin_dev.md)
- [API документация](http://localhost:8001/docs)
- [GitHub Issues](https://github.com/yourusername/ss-tools/issues)

## Поддержка

Если вы столкнулись с проблемами, не описанными в этом документе:

1. Проверьте раздел [Troubleshooting](#troubleshooting)
2. Посмотрите логи в Docker: `docker compose logs -f`
3. Откройте issue на GitHub с подробным описанием проблемы
4. Обратитесь в техническую поддержку