NAM-APJATEL-BACKEND/BULK_IMAGES_QUICK_REF.md

# Device Bulk Operations with Images - Quick Reference

## Endpoints Summary

| Operation | Endpoint | Method | Content-Type |
|-----------|----------|--------|--------------|
| Bulk Create (no images) | `/device/bulk/create` | POST | `application/json` |
| Bulk Create (with images) | `/device/bulk/create` | POST | `multipart/form-data` |
| Bulk Update (no images) | `/device/bulk/update` | PUT | `application/json` |
| Bulk Update (with images) | `/device/bulk/update` | PUT | `multipart/form-data` |
| Bulk Delete | `/device/bulk/delete` | DELETE | `application/json` |

---

## Quick Examples

### Create with Images (cURL)
```bash
curl -X POST http://localhost:8080/device/bulk/create \
  -H "Authorization: Bearer TOKEN" \
  -F 'devices=[{"device_code":"ODP-001","device_type":"ODP","longitude":106.8,"latitude":-6.2,"port_amount":8,"status":"active"}]' \
  -F 'image_indexes=[2]' \
  -F "images=@photo1.jpg" \
  -F "images=@photo2.jpg"
```

### Create with Images (JavaScript)
```javascript
const formData = new FormData();
formData.append('devices', JSON.stringify([
  {
    device_code: "ODP-001",
    device_type: "ODP",
    longitude: 106.8,
    latitude: -6.2,
    port_amount: 8,
    status: "active"
  }
]));
formData.append('image_indexes', JSON.stringify([2])); // 2 images for device
formData.append('images', file1);
formData.append('images', file2);

fetch('/device/bulk/create', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer TOKEN' },
  body: formData
});
```

### Update with Images (JavaScript)
```javascript
const formData = new FormData();
formData.append('device_ids', JSON.stringify([
  "550e8400-e29b-41d4-a716-446655440000"
]));
formData.append('updates', JSON.stringify({ status: "maintenance" }));
formData.append('image_indexes', JSON.stringify([3])); // Add 3 new images
formData.append('replace_images', 'false'); // Append to existing
formData.append('images', file1);
formData.append('images', file2);
formData.append('images', file3);

fetch('/device/bulk/update', {
  method: 'PUT',
  headers: { 'Authorization': 'Bearer TOKEN' },
  body: formData
});
```

---

## Form Fields (Multipart)

### Bulk Create with Images
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `devices` | JSON string | ✅ | Array of device objects |
| `image_indexes` | JSON array | ✅ | Number of images per device |
| `images` | Files | ✅ | Image files in order |

### Bulk Update with Images
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `device_ids` | JSON array | ✅ | Array of UUIDs |
| `updates` | JSON object | ✅ | Fields to update |
| `image_indexes` | JSON array | ✅ | Number of images per device |
| `replace_images` | String | ❌ | "true" or "false" (default: false) |
| `images` | Files | ✅ | Image files in order |

---

## Image Distribution Rules

```javascript
// Example: 3 devices with different image counts
devices = [device1, device2, device3]
image_indexes = [2, 0, 1]  // device1: 2 imgs, device2: 0 imgs, device3: 1 img
images = [img1, img2, img3] // Total: 3 images (2+0+1)

// Result:
// device1 → [img1, img2]
// device2 → []
// device3 → [img3]
```

**Rules:**
- ✅ `len(image_indexes) == len(devices)` or `len(device_ids)`
- ✅ `sum(image_indexes) == len(images)`
- ✅ Images assigned in sequential order

---

## Response Format

```json
{
  "message": "Bulk create completed: 2 successful, 0 failed out of 2 requested (with 3 images)",
  "data": {
    "total_requested": 2,
    "successful": 2,
    "failed": 0,
    "errors": [],
    "results": [
      {
        "id": "uuid-here",
        "device_code": "ODP-001",
        "image_url": "/uploads/devices/primary.jpg",
        "image_urls": [
          "/uploads/devices/primary.jpg",
          "/uploads/devices/secondary.jpg"
        ]
      }
    ],
    "execution_time": "150ms"
  }
}
```

---

## Validation

### Device
- ✅ Type: "ODP", "OTB", or "closure"
- ✅ Status: "active", "inactive", or "maintenance"
- ✅ Port amount > 0 for ODP/OTB
- ✅ OLT only for ODP devices

### Images
- ✅ Max size: 5MB per file
- ✅ Formats: .jpg, .jpeg, .png, .webp
- ✅ Max request: 100MB total

---

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `image_indexes length (3) must match devices length (2)` | Mismatch in array lengths | Ensure `len(image_indexes) == len(devices)` |
| `total images (5) doesn't match sum (4)` | Wrong image count | Ensure `sum(image_indexes) == len(images)` |
| `file size exceeds 5MB limit` | Image too large | Compress image or reduce quality |
| `Invalid device type` | Wrong type value | Use "ODP", "OTB", or "closure" |
| `Only ODP devices can be assigned to OLT` | OLT on wrong type | Only set `olt_id` for ODP devices |

---

## Performance Tips

✅ Keep batches under 50 devices  
✅ Compress images before upload  
✅ Use JSON mode when no images needed  
✅ Check errors array for partial failures  
✅ 4-10x faster than individual requests  

---

## Testing with Postman

1. **Method**: POST or PUT
2. **URL**: `http://localhost:8080/device/bulk/create`
3. **Headers**: 
   - `Authorization: Bearer YOUR_TOKEN`
4. **Body**: `form-data`
   - `devices` (Text): `[{...}]`
   - `image_indexes` (Text): `[2,1]`
   - `images` (File): Select files
   - `images` (File): Select files
   - `images` (File): Select files

---

## Authorization

**Required Roles**: Teknisi, Admin, Super Admin  
**Header**: `Authorization: Bearer JWT_TOKEN`

---

## See Full Documentation

📖 [DEVICE_BULK_IMAGES_GUIDE.md](./DEVICE_BULK_IMAGES_GUIDE.md) - Complete guide with all details