F7_recording/PROJECT_STRUCTURE.md

# Структура проекта F7cloud Talk Recording Server

## Обзор

Этот документ описывает структуру проекта и назначение каждого компонента для удобной навигации и использования при развертывании.

## Основная структура

```
f7cloud-talk-recording/
│
├── src/                                    # Исходный код приложения
│   └── f7cloud/
│       └── talk/
│           └── recording/                 # Основной модуль записи
│               ├── __init__.py            # Инициализация модуля, версия, константы
│               ├── __main__.py            # Точка входа CLI (команда f7cloud-talk-recording)
│               ├── Server.py              # HTTP сервер (Flask), обработка API запросов
│               ├── Service.py             # Сервис записи (управление процессом записи)
│               ├── Config.py              # Управление конфигурацией из server.conf
│               ├── Participant.py         # Управление участником в браузере (Selenium)
│               ├── BackendNotifier.py     # Уведомления бэкенда F7cloud
│               ├── RecorderArgumentsBuilder.py  # Построитель аргументов для FFmpeg
│               └── Benchmark.py           # Утилита для бенчмарков
│
├── dependencies/                          # Внешние зависимости (не требуют установки из репозиториев)
│   ├── firefox-esr/                       # Firefox ESR - браузер для записи
│   │   ├── firefox                        # Исполняемый файл Firefox
│   │   └── ...                            # Остальные файлы Firefox
│   └── geckodriver                        # Geckodriver - драйвер Selenium для Firefox
│
├── tests/                                 # Тесты
│   ├── ServerTest.py                     # Тесты HTTP сервера
│   └── ConfigTest.py                     # Тесты конфигурации
│
├── server.conf.in                        # Шаблон конфигурационного файла
│                                          # Копируется в /etc/f7cloud-talk-recording/server.conf при установке
│
├── pyproject.toml                        # Конфигурация Python проекта
│                                          # Содержит зависимости, метаданные, скрипты
│
├── install.sh                            # Скрипт автоматической установки
│                                          # Устанавливает все зависимости и настраивает систему
│
├── INSTALL.md                            # Подробная инструкция по установке
├── README.md                             # Основная документация проекта
└── PROJECT_STRUCTURE.md                  # Этот файл
```

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

### src/f7cloud/talk/recording/

#### __init__.py
- Версия пакета (`__version__`)
- Константы статусов записи (`RECORDING_STATUS_AUDIO_AND_VIDEO`, `RECORDING_STATUS_AUDIO_ONLY`)
- User-Agent для HTTP запросов

#### __main__.py
- Точка входа для команды `f7cloud-talk-recording`
- Парсинг аргументов командной строки
- Загрузка конфигурации и запуск сервера

#### Server.py
- HTTP сервер на Flask
- Обработка запросов на начало/конец записи
- Prometheus metrics endpoint
- Валидация запросов и аутентификация

#### Service.py
- Класс `Service` - основной сервис записи
- Управление виртуальным дисплеем (Xvfb)
- Управление аудио sink (PulseAudio)
- Запуск браузера и FFmpeg
- Загрузка записи на сервер

#### Config.py
- Класс `Config` - управление конфигурацией
- Чтение и парсинг `server.conf`
- Методы для получения настроек бэкенда, signaling, записи

#### Participant.py
- Класс `Participant` - управление участником в браузере
- Класс `SeleniumHelper` - работа с Selenium WebDriver
- Открытие страницы записи
- Подключение к signaling серверу
- Управление медиа потоками

#### BackendNotifier.py
- Функции для отправки уведомлений бэкенду F7cloud
- `started()` - уведомление о начале записи
- `stopped()` - уведомление о конце записи
- `failed()` - уведомление об ошибке
- `uploadRecording()` - загрузка записи на сервер

#### RecorderArgumentsBuilder.py
- Построитель аргументов командной строки для FFmpeg
- Формирование команд для записи аудио и видео

#### Benchmark.py
- Утилита для бенчмарков производительности
- Тестирование записи с различными параметрами

### dependencies/

#### firefox-esr/
Firefox ESR (Extended Support Release) - стабильная версия Firefox для корпоративного использования.
- Используется для записи видеозвонков
- Запускается в headless режиме через Selenium
- Устанавливается в `/opt/firefox-esr` при установке

#### geckodriver
Драйвер Selenium для Firefox.
- Используется для управления Firefox через Selenium WebDriver
- Устанавливается в `/usr/local/bin/geckodriver` при установке

### Конфигурационные файлы

#### server.conf.in
Шаблон конфигурационного файла. Содержит секции:
- `[logs]` - уровень логирования
- `[http]` - настройки HTTP сервера
- `[app]` - настройки приложения (trusted proxies)
- `[backend]` - общие настройки бэкенда
- `[backend-id]` - настройки конкретного бэкенда F7cloud
- `[signaling]` - настройки signaling сервера
- `[ffmpeg]` - настройки FFmpeg
- `[recording]` - настройки записи (браузер, пути)
- `[stats]` - настройки статистики

#### pyproject.toml
Конфигурация Python проекта:
- Метаданные проекта (имя, описание, авторы)
- Зависимости Python
- Entry points (команды CLI)
- Настройки инструментов (pylint, pytest)

### Скрипты

#### install.sh
Автоматический скрипт установки:
1. Устанавливает системные зависимости
2. Устанавливает Firefox ESR и Geckodriver
3. Создает виртуальное окружение Python
4. Устанавливает Python-зависимости
5. Создает пользователя `f7cloud-talk-recording`
6. Копирует конфигурацию
7. Создает systemd service

## Потоки данных

### Процесс записи

1. **Запрос на запись** → Server.py получает HTTP запрос
2. **Валидация** → Server.py проверяет запрос и создает Service
3. **Инициализация** → Service.py создает виртуальный дисплей и аудио sink
4. **Браузер** → Participant.py запускает Firefox через Selenium
5. **Подключение** → Participant.py открывает страницу записи и подключается к signaling
6. **Запись** → Service.py запускает FFmpeg для записи дисплея и аудио
7. **Завершение** → Service.py останавливает запись и загружает файл через BackendNotifier.py

### Взаимодействие компонентов

```
HTTP Request → Server.py
                ↓
            Service.py
                ↓
        ┌──────┴──────┐
        ↓             ↓
    Participant.py  FFmpeg
    (Selenium)      (запись)
        ↓             ↓
    BackendNotifier.py
        ↓
    F7cloud Server
```

## Установка и развертывание

### Автоматическая установка

```bash
sudo ./install.sh
```

### Ручная установка

См. `INSTALL.md` для подробных инструкций.

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

1. Редактировать `/etc/f7cloud-talk-recording/server.conf`
2. Запустить: `sudo systemctl start f7cloud-talk-recording`
3. Включить автозапуск: `sudo systemctl enable f7cloud-talk-recording`

## Разработка

### Структура для разработчиков

- `src/` - исходный код
- `tests/` - тесты
- `pyproject.toml` - зависимости и настройки

### Запуск для разработки

```bash
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
f7cloud-talk-recording --config server.conf.in
```

## Полезные команды

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

```bash
# Проверка Firefox
/usr/local/bin/firefox-esr --version

# Проверка Geckodriver
/usr/local/bin/geckodriver --version

# Проверка Python пакета
source venv/bin/activate
f7cloud-talk-recording --version
```

### Логи и отладка

```bash
# Логи systemd
sudo journalctl -u f7cloud-talk-recording -f

# Ручной запуск с логами
source venv/bin/activate
f7cloud-talk-recording --config /etc/f7cloud-talk-recording/server.conf
```

## Дополнительная информация

- `INSTALL.md` - подробная инструкция по установке
- `README.md` - основная документация
- `server.conf.in` - комментарии в конфигурации содержат описание всех параметров