# Device Bulk Operations - Quick Reference

## 🚀 New Endpoints

### Bulk Create Devices
```bash
POST /devices/bulk/create
```
```json
{
  "devices": [
    {
      "device_code": "ODP-001",
      "device_type": "ODP",
      "longitude": 107.6191,
      "latitude": -6.9175,
      "port_amount": 8,
      "status": "active",
      "province": "West Java",
      "city": "Bandung",
      "district": "Cicadas",
      "tower_id": "uuid-optional",
      "olt_id": "uuid-optional-for-odp"
    }
  ]
}
```

### Bulk Update Devices
```bash
PUT /devices/bulk/update
```
```json
{
  "device_ids": ["uuid1", "uuid2"],
  "updates": {
    "status": "maintenance",
    "province": "Central Java"
  }
}
```

### Bulk Delete Devices
```bash
DELETE /devices/bulk/delete
```
```json
{
  "device_ids": ["uuid1", "uuid2", "uuid3"]
}
```

## ✅ Validation Rules

### Device Types
- `ODP` - Optical Distribution Point (can be assigned to OLT)
- `OTB` - Optical Terminal Box
- `closure` - Cable Closure

### Status Values
- `active`
- `inactive`
- `maintenance`

### Important Notes
1. **Port Amount**: Required for OTB and ODP devices (must be > 0)
2. **OLT Assignment**: Only ODP devices can be assigned to an OLT
3. **Tower Assignment**: Optional for all device types
4. **Limits**: Maximum 100 devices per bulk operation

## 📊 Response Format
```json
{
  "total_requested": 10,
  "successful": 8,
  "failed": 2,
  "errors": [
    {
      "index": 3,
      "error": "Invalid port amount",
      "details": "port amount must be greater than 0 for OTB or ODP devices"
    }
  ],
  "results": [/* array of created/updated devices */],
  "execution_time": "320ms"
}
```

## 🔐 Authorization
Requires role: `Teknisi` | `Admin` | `Super Admin`

## ⚡ Performance
- **5-10x faster** than individual operations
- Optimal batch size: 20-50 devices
- Transaction-safe operations
- Batch processing: 50 items per database transaction

## 📝 Example Usage

### PowerShell (Windows)
```powershell
$body = @{
    devices = @(
        @{
            device_code = "ODP-001"
            device_type = "ODP"
            longitude = 107.6191
            latitude = -6.9175
            port_amount = 8
            status = "active"
            province = "West Java"
            city = "Bandung"
        }
    )
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Uri "http://localhost:8080/devices/bulk/create" `
    -Method POST `
    -Headers @{
        "Authorization" = "Bearer $token"
        "Content-Type" = "application/json"
    } `
    -Body $body
```

### cURL (Linux/Mac)
```bash
curl -X POST http://localhost:8080/devices/bulk/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "devices": [
      {
        "device_code": "ODP-001",
        "device_type": "ODP",
        "longitude": 107.6191,
        "latitude": -6.9175,
        "port_amount": 8,
        "status": "active"
      }
    ]
  }'
```

## 🔧 Common Use Cases

1. **Initial Deployment**: Bulk create multiple devices from installation plan
2. **Status Updates**: Bulk update device status during maintenance
3. **Network Cleanup**: Bulk delete obsolete or replaced devices
4. **Configuration Changes**: Bulk update device properties
5. **Migration**: Import devices from external systems

## ⚠️ Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| "Invalid port amount" | Port amount ≤ 0 for OTB/ODP | Set port_amount > 0 |
| "Tower not found" | Tower ID doesn't exist | Verify tower exists |
| "OLT not found" | OLT ID doesn't exist | Verify OLT exists |
| "Invalid OLT assignment" | Non-ODP assigned to OLT | Only assign OLT to ODP devices |
| "Device not found" | ID doesn't exist (update/delete) | Verify device ID |

## 📚 Related Documentation
- Cable Connections Bulk: `BULK_OPERATIONS_GUIDE.md`
- API Routes: `API_ROUTES_CABLE_CONNECTIONS.md`
- Quick Reference: `BULK_OPERATIONS_QUICK_REF.md`

---

**Added:** October 10, 2025  
**Version:** 1.0 (Device Bulk Operations)