# Knocker Desktop - Electron приложение

Независимое десктопное приложение для Port Knocker с полным функционалом веб-версии.

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

### Установка и запуск

```bash
cd desktop
npm install
npm run start
```

### Сборка для продакшена

```bash
# Сборка для текущей платформы
npm run build

# Сборка для конкретных платформ
npm run build:win    # Windows
npm run build:linux  # Linux
npm run build:mac    # macOS

# Упаковка без установщика (для тестирования)
npm run pack
```

## 🏗️ Архитектура приложения

### Структура проекта

``` text
desktop/
├── src/
│   ├── main/           # Основной процесс Electron
│   │   ├── main.js     # Точка входа, управление окнами
│   │   └── main.ts     # TypeScript версия (опционально)
│   ├── preload/        # Preload скрипты (мост между main и renderer)
│   │   ├── preload.js  # Безопасный API для renderer процесса
│   │   └── preload.ts  # TypeScript версия
│   └── renderer/       # Процесс рендеринга (UI)
│       ├── index.html  # HTML разметка
│       ├── styles.css  # Стили
│       ├── renderer.js # Логика UI (ванильный JS)
│       └── renderer.ts # TypeScript версия
├── assets/             # Иконки для сборки
├── dist/              # Собранные приложения
├── package.json       # Конфигурация и зависимости
└── README.md          # Документация
```

### Как работает Electron

Electron состоит из двух основных процессов:

1. **Main Process (Основной процесс)** - `src/main/main.js`
   - Управляет жизненным циклом приложения
   - Создает и управляет окнами браузера
   - Обеспечивает безопасный доступ к Node.js API
   - Обрабатывает системные события (закрытие, фокус и т.д.)

2. **Renderer Process (Процесс рендеринга)** - `src/renderer/`
   - Отображает пользовательский интерфейс
   - Работает как обычная веб-страница (HTML/CSS/JS)
   - Изолирован от Node.js API по соображениям безопасности
   - Взаимодействует с main процессом через IPC (Inter-Process Communication)

3. **Preload Script (Preload скрипт)** - `src/preload/preload.js`
   - Выполняется в renderer процессе, но имеет доступ к Node.js API
   - Создает безопасный мост между main и renderer процессами
   - Экспонирует только необходимые API через `contextBridge`

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

Приложение использует современные принципы безопасности Electron:

- `contextIsolation: true` - изолирует контекст renderer от Node.js
- `nodeIntegration: false` - отключает прямой доступ к Node.js в renderer
- `sandbox: false` - позволяет preload скрипту работать (но только в preload)

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

### Локальная разработка

```bash
npm run dev
```

Откроет приложение с включенными DevTools для отладки.

### Структура кода

#### Main Process (`src/main/main.js`)

```javascript
const { app, BrowserWindow, ipcMain, dialog } = require('electron');

// Создание главного окна
function createWindow() {
  mainWindow = new BrowserWindow({
    width: 1100,
    height: 800,
    webPreferences: {
      preload: path.join(__dirname, '../preload/preload.js'),
      contextIsolation: true,  // Безопасность
      nodeIntegration: false,  // Безопасность
      sandbox: false           // Для preload
    }
  });
}

// IPC обработчики для файловых операций
ipcMain.handle('file:open', async () => {
  const res = await dialog.showOpenDialog({...});
  // Возвращает файл в renderer процесс
});
```

#### Preload Script (`src/preload/preload.js`)

```javascript
const { contextBridge, ipcRenderer } = require('electron');

// Безопасный API для renderer процесса
contextBridge.exposeInMainWorld('api', {
  openFile: () => ipcRenderer.invoke('file:open'),
  saveAs: (payload) => ipcRenderer.invoke('file:saveAs', payload),
  // ... другие методы
});
```

#### Renderer Process (`src/renderer/renderer.js`)

```javascript
// Используем безопасный API из preload
window.addEventListener('DOMContentLoaded', () => {
  document.getElementById('openFile').addEventListener('click', async () => {
    const result = await window.api.openFile();
    // Обрабатываем результат
  });
});
```

### Функциональность

#### Режимы работы

1. **Inline режим** - простые поля для ввода targets, delay, verbose
2. **YAML режим** - редактирование YAML конфигурации с поддержкой файлов
3. **Form режим** - табличная форма для добавления/удаления целей

#### Файловые операции

- Открытие файлов через системный диалог
- Сохранение файлов с предложением имени
- Автоматическое извлечение `path` из YAML
- Синхронизация между YAML и serverFilePath полем

#### HTTP API

- Вызовы к `http://localhost:8080/api/v1/knock-actions/*`
- Basic Authentication с пользователем `knocker`
- Выполнение knock операций
- Шифрование/дешифрование конфигураций

### Отладка

#### DevTools

DevTools автоматически открываются при запуске в режиме разработки (`npm run dev`).

#### Консольные сообщения

```javascript
// В renderer процессе
console.log('Debug info:', data);

// В main процессе
console.log('Main process log:', data);
```

#### IPC отладка

```javascript
// В preload можно добавить логирование
ipcRenderer.invoke('file:open').then(result => {
  console.log('IPC result:', result);
});
```

## 📦 Сборка и распространение

### Electron Builder конфигурация

В `package.json` настроена конфигурация `electron-builder`:

```json
{
  "build": {
    "appId": "com.knocker.desktop",
    "productName": "Knocker Desktop",
    "files": ["src/**/*", "node_modules/**/*"],
    "win": {
      "target": "nsis",
      "icon": "assets/icon.ico"
    },
    "linux": {
      "target": "AppImage",
      "icon": "assets/icon.png"
    },
    "mac": {
      "target": "dmg",
      "icon": "assets/icon.icns"
    }
  }
}
```

### Типы сборки

- **NSIS** (Windows) - установщик с мастером установки
- **AppImage** (Linux) - портативное приложение
- **DMG** (macOS) - образ диска для установки

### Команды сборки

```bash
npm run build        # Сборка для текущей платформы
npm run build:win    # Сборка для Windows
npm run build:linux  # Сборка для Linux  
npm run build:mac    # Сборка для macOS
npm run pack         # Упаковка без установщика
npm run dist         # Сборка без публикации
```

### Иконки

Поместите иконки в папку `assets/`:

- `icon.ico` - для Windows (256x256)
- `icon.png` - для Linux (512x512)
- `icon.icns` - для macOS (512x512)

## 🔄 Интеграция с веб-версией

### Общие компоненты

- HTTP API остается тем же (`/api/v1/knock-actions/*`)
- YAML формат конфигурации идентичен
- Логика шифрования/дешифрования совместима

### Различия

- **Файловые операции**: Electron dialog вместо браузерных File API
- **UI библиотеки**: ванильный JS вместо Angular/PrimeNG
- **Автосохранение**: localStorage в веб-версии, файловая система в desktop
- **FSA API**: не нужен в desktop версии

### Миграция данных

Пользователи могут переносить конфигурации между версиями через:

- Экспорт/импорт YAML файлов
- Копирование содержимого между интерфейсами
- Использование одинаковых server paths

## 🐛 Устранение неполадок

### Частые проблемы

#### Приложение не запускается

```bash
# Проверьте зависимости
npm install

# Очистите node_modules
rm -rf node_modules package-lock.json
npm install
```

#### DevTools не открываются

Убедитесь, что в `src/main/main.js` есть строка:

```javascript
mainWindow.webContents.openDevTools();
```

#### Файлы не открываются

Проверьте, что backend сервер запущен на `http://localhost:8080`

#### Сборка не работает

```bash
# Очистите dist папку
rm -rf dist

# Пересоберите
npm run build
```

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

#### Main процесс

Логи main процесса видны в терминале, где запущено приложение.

#### Renderer процесс

Логи renderer процесса видны в DevTools Console.

#### IPC сообщения

Можно добавить логирование в preload для отладки IPC:

```javascript
const originalInvoke = ipcRenderer.invoke;
ipcRenderer.invoke = function(channel, ...args) {
  console.log(`IPC: ${channel}`, args);
  return originalInvoke.call(this, channel, ...args);
};
```

## 📚 Дополнительные ресурсы

- [Electron Documentation](https://www.electronjs.org/docs)
- [Electron Builder](https://www.electron.build/)
- [Context Isolation](https://www.electronjs.org/docs/latest/tutorial/context-isolation)
- [IPC Communication](https://www.electronjs.org/docs/latest/tutorial/ipc)

## 🤝 Вклад в разработку

1. Форкните репозиторий
2. Создайте ветку для новой функции
3. Внесите изменения
4. Протестируйте на всех платформах
5. Создайте Pull Request

### Тестирование

```bash
# Тест на текущей платформе
npm run dev

# Сборка для тестирования
npm run pack

# Проверка на других платформах
npm run build:win
npm run build:linux
npm run build:mac
```