god_eye/docs/OPERATOR_TO_ANDROID_CONNECTION.md

Руководство: Подключение Desktop Operator к Android телефону

🔗 Как работает подключение оператора к телефону

Архитектура подключения

Desktop Operator ←→ WebSocket ←→ Сервер ←→ WebSocket ←→ Android телефон
                                    ↓
                           ConnectionManager
                           (управляет соединениями)
                                    ↓
                            WebRTC P2P соединение
                        (прямая передача видео)

1. 📱 Регистрация Android устройства

Android телефон подключается к серверу:

// Android код
val socket = IO.socket("ws://192.168.1.100:3001")
socket.emit("register:android", JSONObject().apply {
    put("deviceId", "android_unique_id")
    put("deviceInfo", JSONObject().apply {
        put("manufacturer", "Samsung")
        put("model", "Galaxy S21")
        put("androidVersion", "11")
        put("availableCameras", JSONArray(listOf("back", "front", "ultra_wide")))
        put("appVersion", "1.0.0")
    })
})

Сервер подтверждает регистрацию:

// Лог сервера
{"level":"info","message":"Android client registered: android_unique_id","timestamp":"..."}

2. 💻 Подключение Desktop Operator

Operator приложение подключается:

// Desktop Operator код
const socket = io('ws://192.168.1.100:3001');
socket.emit('register:operator', {
    operatorId: 'operator-uuid',
    operatorInfo: {
        name: 'Иван Петров',
        organization: 'Служба безопасности',
        permissions: ['view_cameras', 'request_camera', 'initiate_connection']
    }
});

3. 🔍 Проверка доступных устройств

REST API запрос списка устройств:

curl -H "x-operator-id: operator-uuid" \
     http://localhost:3001/api/operators/devices

Ответ сервера:

{
  "success": true,
  "devices": [
    {
      "deviceId": "android_unique_id",
      "model": "Galaxy S21",
      "manufacturer": "Samsung",
      "isConnected": true,
      "availableCameras": ["back", "front", "ultra_wide"],
      "canAcceptNewSession": true,
      "activeSessions": 0
    }
  ],
  "total": 1
}

4. 📞 Инициация подключения к телефону

Оператор запрашивает доступ к камере:

curl -X POST http://localhost:3001/api/operators/connections/request \
  -H "Content-Type: application/json" \
  -H "x-operator-id: operator-uuid" \
  -d '{
    "deviceId": "android_unique_id",
    "cameraType": "back"
  }'

Сервер создает подключение:

{
  "success": true,
  "connectionId": "conn-uuid",
  "sessionId": "session-uuid",
  "message": "Connection request initiated"
}

5. 📲 Android получает запрос подтверждения

WebSocket событие на Android:

// Сервер → Android
socket.emit('connection:request', {
  connectionId: 'conn-uuid',
  sessionId: 'session-uuid',
  operatorId: 'operator-uuid',
  operatorInfo: {
    name: 'Иван Петров',
    organization: 'Служба безопасности',
    reason: 'Проверка безопасности'
  },
  cameraType: 'back',
  timestamp: '2025-10-04T12:00:00.000Z',
  expiresAt: '2025-10-04T12:05:00.000Z' // 5 минут на ответ
});

Android показывает диалог пользователю:

┌─────────────────────────────────┐
│     Запрос доступа к камере     │
├─────────────────────────────────┤
│ Оператор: Иван Петров          │
│ Организация: Служба безопасности│
│ Причина: Проверка безопасности  │
│ Камера: Задняя                  │
│                                 │
│ Разрешить доступ к камере?      │
│                                 │
│  [Разрешить]    [Отклонить]     │
└─────────────────────────────────┘

6. ✅ Пользователь принимает/отклоняет запрос

Если пользователь принимает:

// Android → Сервер
socket.emit("connection:accept", JSONObject().apply {
    put("connectionId", connectionId)
    put("sessionId", sessionId)
    put("cameraType", "back")
    put("webrtcInfo", JSONObject().apply {
        put("supported", true)
        put("codecs", JSONArray(listOf("H264", "VP8")))
        put("resolutions", JSONArray(listOf("720p", "1080p")))
    })
})

Сервер уведомляет оператора:

// Сервер → Desktop Operator
socket.emit('connection:accepted', {
  connectionId: 'conn-uuid',
  sessionId: 'session-uuid',
  webrtcInfo: {
    supported: true,
    codecs: ['H264', 'VP8'],
    resolutions: ['720p', '1080p']
  }
});

7. 🎥 Установка WebRTC соединения

Обмен WebRTC сигналами:

Desktop Operator → Сервер → Android: webrtc:offer
Android → Сервер → Desktop Operator: webrtc:answer
Desktop Operator ↔ Сервер ↔ Android: webrtc:ice-candidate

После успешного установления WebRTC:

Desktop Operator ←-----WebRTC P2P-----→ Android
                    (прямое видео)

🧪 Тестирование подключения

Проверка 1: Статус системы

curl http://localhost:3001/api/status | jq

Проверка 2: Список устройств

curl -H "x-operator-id: YOUR_OPERATOR_ID" \
     http://localhost:3001/api/operators/devices | jq

Проверка 3: Инициация подключения

curl -X POST http://localhost:3001/api/operators/connections/request \
  -H "Content-Type: application/json" \
  -H "x-operator-id: YOUR_OPERATOR_ID" \
  -d '{
    "deviceId": "android_device_id",
    "cameraType": "back"
  }' | jq

Проверка 4: Статус подключений

curl -H "x-operator-id: YOUR_OPERATOR_ID" \
     http://localhost:3001/api/operators/connections | jq

🐞 Диагностика проблем

Проблема: "Invalid or disconnected operator"

Причина: Оператор не подключен к WebSocket Решение:

1. Откройте веб-демо: http://localhost:3001
2. Проверьте WebSocket подключение в консоли браузера
3. Используйте Operator ID из консоли

Проблема: "Device not found"

Причина: Android устройство не подключено Решение:

1. Перезапустите Android приложение
2. Проверьте сетевое соединение
3. Убедитесь что устройство регистрируется

Проблема: "Device busy or unavailable"

Причина: Устройство занято другой сессией Решение:

1. Завершите активные сессии
2. Подождите таймаут (30 секунд)
3. Попробуйте снова

📊 Мониторинг соединений

Логи сервера

tail -f /home/data/god_eye/backend/god-eye.log

Административная статистика

curl http://localhost:3001/api/admin/stats | jq

Real-time статус через WebSocket

socket.on('device:connected', (data) => {
  console.log('Устройство подключено:', data.deviceId);
});

socket.on('connection:accepted', (data) => {
  console.log('Подключение принято:', data.connectionId);
});

🔒 Безопасность

1. Разрешения пользователя: Android требует подтверждения каждого запроса
2. Таймауты: Запросы автоматически истекают через 5 минут
3. Аутентификация: Проверка Operator ID для всех API запросов
4. Логирование: Все операции записываются в логи

🚀 Быстрый старт

1. Запустите сервер:

   cd /home/data/god_eye/backend && npm start
   

2. Откройте веб-демо: http://localhost:3001

3. Запустите Android приложение и подключите к серверу

4. Инициируйте подключение через веб-интерфейс или API

5. Примите запрос на Android устройстве

6. Наслаждайтесь прямым WebRTC видеопотоком!