# 📊 Bulk Operations - Массовые операции

## ✨ Описание фичи

Bulk Operations позволяют выполнять операции над **группой машин одновременно**, значительно ускоряя административные задачи и мониторинг.

### **Реализованные функции:**
- ✅ **Bulk Health Check** - проверка доступности нескольких машин параллельно
- ✅ **Bulk SSH Command** - выполнение команды на нескольких серверах с 3 режимами авторизации
- 🔜 **Multi-Connect** - открыть подключения к нескольким машинам (planned)
- 🔜 **Bulk Tags Update** - массовое обновление тегов (planned)

---

## 🎯 Use Cases

### **1. Проверка доступности prod серверов**
```
Scenario: Утренний чек перед началом работы
1. Фильтруем по тегу "production"
2. Select All (50 machines)
3. Click "Health Check"
4. Результат: 48 online, 2 offline
5. Быстро идентифицируем проблемы
```

### **2. Массовое выполнение SSH команд**
```
Scenario: Перезапуск сервиса на всех web серверах
1. Фильтруем по тегу "webserver"
2. Select All (15 machines)
3. Click "Run Command"
4. Command: "systemctl restart nginx"
5. Mode: Saved credentials
6. Result: 15/15 success
```

---

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

### **Step 1: Enable Bulk Mode**
```
1. В Sidebar → Click "Bulk Select"
2. Кнопка меняется на "✓ Bulk Mode"
3. Появляются checkboxes возле машин
```

### **Step 2: Select Machines**
```
Опция A: Manual selection
  - Click checkboxes вручную

Опция B: Select All
  - Click "Select All" checkbox
  - Все машины выбраны

Опция C: With filter
  - Search: "web"
  - Select All → только отфильтрованные
```

### **Step 3: Choose Operation**
```
Toolbar появляется внизу:
[Health Check] [Run Command] [Multi-Connect] [Update Tags]
```

---

## 📖 Детальные руководства

- **[BULK_SSH_COMMANDS_GUIDE.md](./BULK_SSH_COMMANDS_GUIDE.md)** - SSH Commands с 3 режимами авторизации
- **Health Check** - см. ниже в этом документе

---

## 🏥 Bulk Health Check

### **Описание:**
Параллельная проверка доступности нескольких машин одновременно.

**Features:**
- DNS resolution check
- TCP port connectivity check
- Response time measurement
- Role-based limits

### **API:**
```
POST /bulk/health-check

Request:
{
  "machine_ids": ["abc...", "def...", "ghi..."],
  "timeout": 5,
  "check_port": true
}

Response:
{
  "total": 3,
  "available": 2,
  "unavailable": 1,
  "execution_time_ms": 1250,
  "results": [...]
}
```

### **Role Limits:**
- **GUEST:** max 10 machines
- **USER:** max 50 machines
- **ADMIN:** max 200 machines

### **UI Flow:**
```
1. Select machines → Bulk mode
2. Click "Health Check"
3. Progress modal shows: "Checking 15/50 machines..."
4. Results modal: 
   - Tabs: All / Available / Unavailable
   - Sortable table
   - Export CSV
   - Retry Failed
```

---

## 🔐 Security & Permissions

### **Role-based Access:**

| Feature | GUEST | USER | ADMIN |
|---------|-------|------|-------|
| Health Check | 10 machines | 50 machines | 200 machines |
| SSH Command | ❌ Forbidden | 20 machines (whitelist) | 100 machines (any) |
| Multi-Connect | 2 machines | 5 machines | 10 machines |

### **Audit Logging:**
```json
{
  "action": "bulk_health_check",
  "user": "admin",
  "machine_count": 50,
  "available": 48,
  "unavailable": 2,
  "execution_time_ms": 3500,
  "timestamp": "2025-01-15T10:30:00Z"
}
```

---

## 📊 Performance

| Operation | 10 machines | 50 machines | 100 machines |
|-----------|------------|-------------|--------------|
| Health Check | ~500ms | ~2.5s | ~5s |
| SSH Command | ~2s | ~10s | ~20s |

**Optimization:**
- Parallel execution via `asyncio.gather`
- Configurable timeouts
- Semaphore для SSH (max 10 concurrent)

---

## 🎓 Best Practices

### **1. Используйте фильтры перед bulk selection**
```
✅ Good: Filter → Select All filtered → Health Check
❌ Bad: Select All 1000 machines → try to Health Check → error
```

### **2. Export результаты для отчетов**
```
Use case: Weekly infrastructure report
1. Select all prod servers
2. Health Check
3. Export CSV
4. Import to Excel/Dashboard
```

### **3. Retry Failed для устранения false negatives**
```
Scenario: Network glitch
1. Health Check → 5 machines offline
2. Wait 30 seconds
3. Retry Failed → 3 now online
4. Investigate remaining 2
```

---

## 🐛 Troubleshooting

### **Issue: "Selection Limit Exceeded"**
```
Error: "Role USER can check max 50 machines at once"

Solution:
1. Проверить свою роль (Header → User Info)
2. Уменьшить выбор машин
3. Запросить upgrade роли у администратора
```

### **Issue: All machines show "Unavailable"**
```
Possible causes:
1. Network issues on server side
2. Firewall blocking ports
3. DNS resolution problems

Debug:
1. Check API logs: docker compose logs remote_access_api
2. Try single machine health check first
3. Verify network connectivity from API container
```

---

## 🔗 Related Documentation

- [BULK_SSH_COMMANDS_GUIDE.md](./BULK_SSH_COMMANDS_GUIDE.md) - 📘 **Детальное руководство по SSH Commands**
- [AUTHENTICATION_FLOW_DETAILED.md](./AUTHENTICATION_FLOW_DETAILED.md) - Role-based permissions
- [PRODUCTION_SECURITY_ARCHITECTURE.md](./PRODUCTION_SECURITY_ARCHITECTURE.md) - Audit logging
- [SAVED_MACHINES_FEATURE.md](./SAVED_MACHINES_FEATURE.md) - Machine management

---

**🎉 Готово! Bulk Operations полностью реализованы и документированы.**

### **Что реализовано:**
1. ✅ **Bulk Health Check** - Массовая проверка доступности
2. ✅ **Bulk SSH Command** - Массовое выполнение команд с 3 режимами авторизации