main commit

docs/CONNECTION_MANAGER.md

@@ -0,0 +1,316 @@
+# 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` (клиентские методы)