# Руководство по локальному запуску (Local Setup)

В этом документе описаны шаги для поднятия проекта на рабочей машине разработчика или для проведения презентации (демо). Проект поддерживает как легковесный запуск на SQLite, так и масштабируемый запуск с использованием PostgreSQL и RabbitMQ.

## 1. Системные требования
- **Python 3.10+** (для микросервисов)
- **Docker и Docker Compose** (для запуска PostgreSQL, RabbitMQ и т.д.)
- **PowerShell** (основные launch-скрипты написаны на нём)

## 2. Быстрый старт: Режим ДЕМО (Автоматически)

Самый удобный способ поднять весь стек контакт-центра одной командой. Скрипт запустит сервисы, прогонит смоук-тесты и заполнит базу моковыми данными:

```powershell
powershell -ExecutionPolicy Bypass -File scripts\prepare_demo.ps1
```

**Что делает `prepare_demo.ps1`**:
- Поднимает все микросервисы проекта в фоне (логи складываются в папку `.local_stack\logs`).
- Создает тестового клиента и историю его взаимодействия.
- Симулирует звонок с IVR и создает запись в `recording-service`.
- Наливает статьи Базы Знаний.
- Забрасывает метрики для KPI отчетов в `reporting-service`.

**Остановка и очистка:**
```powershell
# Остановить все фоновые процессы сервисов
powershell -ExecutionPolicy Bypass -File scripts\stop_all_local.ps1

# Полностью очистить рабочее пространство сервера (удалить временные БД и артефакты)
powershell -ExecutionPolicy Bypass -File scripts\clean_workspace.ps1
```

## 3. Ручной запуск (Local Development)

Если вы разрабатываете конкретный микросервис и вам нужен горячий рестарт (Hot Reload), поднимайте сервисы вручную.

### Шаг 3.1: Установка зависимостей
```bash
python -m pip install -r requirements.txt
```

### Шаг 3.2: Запуск инфраструктуры (Docker)
Если вы не хотите использовать fallback-режим с SQLite, поднимите PostgreSQL и системные сервисы:
```bash
cd deployment
docker compose up -d postgres
cd ..
```

### Шаг 3.3: Миграции Базы Данных
Перед запуском бизнес-логики необходимо проинициализировать схему БД:
```bash
python scripts/migrate_core_db.py
```

### Шаг 3.4: Запуск Gateway и Микросервисов
Для маршрутизации запросов обязательно должен работать `api-gateway`:
```bash
uvicorn gateway.app:app --reload --port 8080
```
Далее в новых консолях вы можете точечно поднимать необходимые вам микросервисы (по умолчанию Gateway проксирует запросы на порты `8001`, `8004` и т.д.):
```bash
uvicorn services.auth_service.app:app --reload --port 8001
uvicorn services.interaction_service.app:app --reload --port 8004
```

## 4. Точки входа (Пользовательские интерфейсы)

Если `gateway.app` успешно запущен на порту 8080, вы можете попасть в веб-интерфейсы платформы по следующим адресам:

- **Рабочее место Оператора**: [http://localhost:8080/operator](http://localhost:8080/operator)
- **Панель Супервизора**: [http://localhost:8080/supervisor](http://localhost:8080/supervisor)
- **Панель Администратора**: [http://localhost:8080/admin](http://localhost:8080/admin)
- **Аналитика (Дашборды)**: [http://localhost:8080/analyst](http://localhost:8080/analyst)

## 5. Полезные скрипты

В папке `scripts/` лежит множество полезных инструментов для разработки:

```bash
# Прогон всех автотестов
pytest -q

# Смоук-чек авторизации (проверка выдачи JWT токенов)
python scripts/oidc_smoke.py --base-url http://localhost:8080

# Снятие и распаковка бэкапа (дамп данных лок. среды)
powershell -ExecutionPolicy Bypass -File scripts\backup_data.ps1
powershell -ExecutionPolicy Bypass -File scripts\restore_data.ps1 -BackupZip e:\Zhan\backups\mvp_cc_data_YYMMDD.zip

# Нагрузочное тестирование (позволяет сгенерировать фейковый трафик звонков)
python scripts/load_test.py --base-url http://localhost:8080 --profile baseline_100_100
```