god_eye/docs/CONNECTION_MANAGER.md

# ConnectionManager API Документация

## Обзор

`ConnectionManager` - это центральный компонент системы GodEye Signal Center, который управляет полным жизненным циклом подключений между операторами и Android устройствами. Он обеспечивает надежное создание, управление и завершение подключений с таймаутами и валидацией.

## Архитектура

```
Desktop Operator ←→ ConnectionManager ←→ Android Device
                         ↕
                  SessionManager
                  DeviceManager
```

### Основные компоненты:

- **ConnectionManager**: Управление подключениями и их жизненным циклом
- **DeviceManager**: Управление устройствами и операторами  
- **SessionManager**: Управление WebRTC сессиями
- **Socket.IO**: Транспорт для событий подключения

## События WebSocket

### Новые события ConnectionManager

#### `connection:initiated`
Подключение инициировано ConnectionManager
```javascript
{
  connectionId: "conn_uuid",
  sessionId: "session_uuid", 
  deviceId: "device_id",
  cameraType: "back",
  status: "pending",
  createdAt: "2023-..."
}
```

#### `connection:accepted`  
Устройство приняло запрос подключения
```javascript
{
  connectionId: "conn_uuid",
  sessionId: "session_uuid",
  deviceId: "device_id", 
  cameraType: "back",
  streamUrl: "webrtc_stream_url",
  status: "active"
}
```

#### `connection:rejected`
Устройство отклонило запрос подключения
```javascript
{
  sessionId: "session_uuid",
  deviceId: "device_id",
  cameraType: "back", 
  error: "Device camera is busy"
}
```

#### `connection:terminated`
Подключение завершено
```javascript
{
  connectionId: "conn_uuid",
  timestamp: "2023-..."
}
```

#### `connection:error`
Ошибка подключения
```javascript
{
  error: "Error message"
}
```

### Команды от клиента

#### `connection:terminate`
Завершить подключение
```javascript
{
  connectionId: "conn_uuid"
}
```

#### `connection:status`
Запросить статистику подключений
```javascript
{} // Ответ в callback или connection:status_response
```

#### `connection:list`
Список подключений оператора
```javascript
{} // Ответ в callback или connection:list_response
```

## Desktop Operator API

### Новые методы

#### `terminateConnection(connectionId, sessionId)`
Завершает подключение через ConnectionManager
```javascript
operator.terminateConnection('conn_123', 'session_456');
```

#### `getConnectionStatus()`
Получает статистику всех подключений системы
```javascript
operator.getConnectionStatus();
```

#### `listMyConnections()`
Получает список подключений текущего оператора
```javascript
operator.listMyConnections();
```

### Обновленные методы

#### `requestCamera(deviceId, cameraType)`
Теперь использует ConnectionManager для создания подключений
```javascript
operator.requestCamera('device_123', 'back');
```

## Backend ConnectionManager API

### Основные методы

#### `async initiateConnection(operatorId, deviceId, cameraType)`
Инициирует новое подключение между оператором и устройством
```javascript
const connection = await connectionManager.initiateConnection(
  'operator_123', 
  'device_456', 
  'back'
);
```

#### `async acceptConnection(sessionId, metadata)`  
Принимает подключение со стороны устройства
```javascript
const connection = await connectionManager.acceptConnection(
  'session_123',
  { streamUrl: 'webrtc://...' }
);
```

#### `async rejectConnection(sessionId, reason)`
Отклоняет подключение
```javascript
await connectionManager.rejectConnection(
  'session_123',
  'Camera is busy'
);
```

#### `async terminateConnection(connectionId)`
Завершает активное подключение
```javascript
await connectionManager.terminateConnection('conn_123');
```

### Утилиты

#### `getConnection(sessionId)`
Получает подключение по ID сессии
```javascript
const connection = connectionManager.getConnection('session_123');
```

#### `getConnectionStats()`
Получает статистику всех подключений
```javascript
const stats = connectionManager.getConnectionStats();
// { total: 5, active: 2, pending: 1, completed: 2 }
```

#### `getOperatorConnections(operatorId)`
Получает все подключения оператора
```javascript
const connections = connectionManager.getOperatorConnections('operator_123');
```

#### `cleanup*()`
Методы очистки подключений при отключении участников
```javascript
connectionManager.cleanupDeviceConnections('device_123');
connectionManager.cleanupOperatorConnections('operator_456');
```

## Жизненный цикл подключения

### 1. Инициирование подключения
```
Desktop Operator → camera:request → ConnectionManager.initiateConnection()
                                 ↓
                              Создание Connection объекта
                                 ↓  
                              Отправка camera:request → Android Device
                                 ↓
Desktop Operator ← connection:initiated ← ConnectionManager
```

### 2. Ответ устройства
```
Android Device → camera:response → ConnectionManager.acceptConnection()
                                 ↓
                              Обновление Connection статуса
                                 ↓
Desktop Operator ← connection:accepted ← ConnectionManager
                                 ↓
                              Инициирование WebRTC
```

### 3. Завершение подключения
```
Desktop Operator → connection:terminate → ConnectionManager.terminateConnection()
                                        ↓
                                     Очистка ресурсов
                                        ↓  
                  connection:terminated ← ConnectionManager
```

## Конфигурация таймаутов

```javascript
// В ConnectionManager.js
CONNECTION_TIMEOUT: 30000,  // 30 секунд на установку подключения
CLEANUP_INTERVAL: 60000     // Очистка каждую минуту
```

## Обратная совместимость

Система поддерживает старые события для совместимости:
- `session:created` → `connection:initiated`
- `session:accepted` → `connection:accepted`  
- `session:rejected` → `connection:rejected`
- `camera:response` (продолжает работать)

## Логирование

ConnectionManager использует Winston logger для отслеживания:
- ✅ Успешные подключения
- ❌ Ошибки и отклонения  
- 🔄 Переходы состояний
- ⏰ Таймауты подключений
- 🧹 Операции очистки

## Примеры использования

### Полный цикл подключения от Desktop Operator

```javascript
// 1. Инициирование подключения
operator.requestCamera('device_123', 'back');

// 2. Обработка ответа
operator.socket.on('connection:accepted', (data) => {
  console.log('Подключение установлено:', data.connectionId);
  // Запускаем WebRTC...
});

// 3. Завершение подключения
operator.terminateConnection(connectionId, sessionId);
```

### Мониторинг подключений

```javascript
// Получение статистики
operator.getConnectionStatus();

// Список моих подключений  
operator.listMyConnections();

// Обработка ошибок
operator.socket.on('connection:error', (data) => {
  console.error('Ошибка подключения:', data.error);
});
```

## Миграция с старой системы

Старые методы продолжают работать, но рекомендуется переход на новые:

### Было:
```javascript
operator.socket.on('session:created', ...);
operator.socket.on('session:accepted', ...);
```

### Стало:
```javascript  
operator.socket.on('connection:initiated', ...);
operator.socket.on('connection:accepted', ...);
```

### UI обновления
- Кнопки завершения сессий теперь используют `terminateConnection()`
- Статус подключений отображается с `connectionId`
- Добавлены индикаторы состояния подключений

---

Для дополнительной информации см. исходный код:
- `/backend/src/managers/ConnectionManager.js`
- `/backend/src/server.js` (обработчики событий)
- `/desktop-operator/src/renderer/app.js` (клиентские методы)