# VPS Интеграция между Главным сайтом и Панелью управления

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

### Для разработчика главного сайта
**Файл:** `FOR_MAIN_SITE_DEVELOPER.md`

Читайте этот файл если вы разработчик **ospab.host** (главный сайт)

Содержит:
- ✅ Как установить переменные окружения
- ✅ Готовый TypeScript сервис для синхронизации
- ✅ Примеры использования в Express
- ✅ Обработка ошибок и retry logic
- ✅ Тестирование через curl

### Для разработчика панели управления
**Файл:** `CLIENT_VPS_INTEGRATION.md`

Читайте этот файл если вы разработчик **ospab-panel** (панель управления)

Содержит:
- ✅ Полную архитектуру и диаграммы
- ✅ Описание таблицы VPS в БД
- ✅ Все API эндпоинты и их параметры
- ✅ Схему авторизации (JWT + API Key)
- ✅ Примеры запросов
- ✅ Таблицу соответствия полей

### Для интеграции (кроссплатформенное)
**Файл:** `VPS_SYNC_EXAMPLES.md`

Примеры кода на разных языках:
- ✅ Node.js / TypeScript
- ✅ Python
- ✅ curl для тестирования

Примеры операций:
- ✅ Создание VPS
- ✅ Обновление статуса
- ✅ Удаление VPS

### Быстрый старт
**Файл:** `VPS_SYNC_QUICK_START.md`

TL;DR версия - что нужно сделать прямо сейчас (5 минут на прочтение)

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

```
┌──────────────────────────────┐
│     Главный сайт             │
│    (ospab.host)              │
│                              │
│  - Каталог тарифов           │
│  - Оплата                    │
│  - Создание VPS              │
└────────────┬─────────────────┘
             │
             │ POST /api/vps/sync
             │ (X-API-Key: secret)
             │
             ▼
┌──────────────────────────────────┐
│   Панель управления              │
│   (ospab-panel)                  │
│                                  │
│  POST /api/vps/sync              │
│  - Создать VPS                   │
│  - Обновить статус               │
│  - Удалить VPS                   │
│                                  │
│  GET /api/vps                    │
│  - Получить список VPS           │
│  (требует JWT токен)             │
│                                  │
└────────────┬─────────────────────┘
             │
             ▼
      ┌────────────────┐
      │  MySQL БД      │
      │  (VPS table)   │
      └────────────────┘
```

## 🔄 Workflow

### Создание VPS

```
1. Пользователь на главном сайте выбирает тариф
                    ↓
2. Оплачивает заказ
                    ↓
3. Главный сайт создает VPS на Proxmox/VMware
                    ↓
4. Главный сайт отправляет POST /api/vps/sync (action: create)
   с параметрами: user_id, name, cpu, ram, disk, os
                    ↓
5. Панель управления сохраняет VPS в БД
                    ↓
6. Главный сайт обновляет статус на "running" (action: update)
                    ↓
7. Клиент видит VPS в Панели управления и может им управлять
```

### Изменение статуса VPS

```
1. Администратор меняет статус VPS на хостинге
                    ↓
2. Главный сайт получает информацию об изменении
                    ↓
3. Главный сайт отправляет POST /api/vps/sync (action: update)
   с параметрами: id, status
                    ↓
4. Панель управления обновляет запись в БД
                    ↓
5. Клиент видит актуальный статус в Панели управления
```

### Удаление VPS

```
1. Клиент отменяет услугу на главном сайте
                    ↓
2. Главный сайт удаляет VPS с хостинга
                    ↓
3. Главный сайт отправляет POST /api/vps/sync (action: delete)
   с параметром: id
                    ↓
4. Панель управления удаляет запись из БД
                    ↓
5. VPS исчезает из списка в Панели управления
```

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

### API Key (для главного сайта)

```
Запрос:
POST /api/vps/sync
X-API-Key: your_secret_api_key_here

Проверка:
- Ключ должен быть в переменной VPS_SYNC_API_KEY на Панели
- Ключи на главном сайте и Панели должны совпадать
- Минимум 32 символа
```

### JWT Token (для клиентов панели)

```
Запрос:
GET /api/vps
Authorization: Bearer <jwt_token>

Проверка:
- Токен должен быть в заголовке Authorization
- Панель проверяет токен и извлекает user_id
- Возвращаются только VPS этого пользователя
```

## 📊 Таблица соответствия

| Главный сайт | Панель управления | Тип | Примечание |
|--------------|-------------------|-----|-----------|
| userId | user_id | int | ID пользователя из SSO |
| name | name | string | Имя VPS |
| cpu | cpu | int | Количество ядер |
| ram (GB) | ram (MB) | int | **Конвертируется: ×1024** |
| disk | disk | int | Объем диска в GB |
| os | os | string | ОС: Ubuntu 22.04, CentOS 7, etc |
| hypervisor | hypervisor | string | proxmox, vmware, hyperv, kvm, xen |
| status | status | string | creating, running, stopped, suspended |

## 🚀 Начало работы

### Для главного сайта

1. Скачайте `FOR_MAIN_SITE_DEVELOPER.md`
2. Скопируйте пример сервиса из документации
3. Адаптируйте под свой код
4. Добавьте в `.env` переменные
5. Протестируйте через curl

### Для панели управления

✅ Уже готово! API эндпоинт `/api/vps/sync` уже работает

Просто убедитесь что:
- В `.env` установлен `VPS_SYNC_API_KEY`
- Go сервер запущен на корректном порту
- БД доступна и миграции применены

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

### Тест создания VPS

```bash
# Отправить запрос
curl -X POST http://localhost:5050/api/vps/sync \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_secret_api_key_here_min_32_chars_change_this" \
  -d '{
    "action": "create",
    "vps": {
      "user_id": 5,
      "name": "test-vps-01",
      "status": "creating",
      "cpu": 2,
      "ram": 2048,
      "disk": 50,
      "os": "Ubuntu 22.04 LTS",
      "hypervisor": "proxmox"
    }
  }'

# Ожидаемый ответ (201):
# {
#   "status": "success",
#   "message": "VPS synced successfully",
#   "vps": {
#     "id": 1,
#     "name": "test-vps-01",
#     "status": "creating",
#     ...
#   }
# }
```

### Проверить что VPS в Панели

1. Откройте Панель управления: http://localhost:3000
2. Зайдите под пользователем с ID = 5
3. Перейдите в "Мои серверы"
4. Должен появиться VPS "test-vps-01"

## 📝 Статус реализации

- ✅ API эндпоинт `/api/vps/sync` реализован
- ✅ Методы: create, update, delete готовы
- ✅ Таблица VPS создана в БД
- ✅ Документация написана
- ✅ Примеры кода готовы
- ⏳ Интеграция с главным сайтом (в процессе)

## ❓ Часто задаваемые вопросы

**Q: Почему два разных способа авторизации?**
A: API Key используется для сервер-сервер коммуникации (главный сайт → панель), JWT используется для клиент-сервер (браузер → панель)

**Q: Что если главный сайт отправил неправильные данные?**
A: Панель валидирует все данные и возвращает ошибку 400 Bad Request с описанием проблемы

**Q: Может ли клиент создать VPS через панель напрямую?**
A: Нет, панель только отображает VPS синхронизированные с главного сайта. Создание происходит только через главный сайт.

**Q: Что такое status "creating"?**
A: VPS только что был создан, но еще не полностью готов. После установки ОС статус обновляется на "running"

## 📞 Контакты

- Документация: смотрите файлы в репозитории
- Вопросы по API: читайте `CLIENT_VPS_INTEGRATION.md`
- Примеры: читайте `VPS_SYNC_EXAMPLES.md`
- Для главного сайта: читайте `FOR_MAIN_SITE_DEVELOPER.md`

---

**Версия:** 1.0  
**Дата:** 27 октября 2025  
**Статус:** Готово к интеграции ✅