NAM-APJATEL-BACKEND/BULK_OPERATIONS_GUIDE.md

# Cable Connections Bulk Operations Guide

## Overview
This guide explains how to use the bulk insert, update, and delete operations for cable connections in the Network Asset Management system.

## API Endpoints

### 1. Bulk Create Cable Connections
**Endpoint:** `POST /cable-connections/bulk/create`

**Description:** Create multiple cable connections in a single request (up to 100 at once).

**Request Body:**
```json
{
  "connections": [
    {
      "from_device_id": "uuid-1",
      "to_device_id": "uuid-2",
      "cable_length": 150.5,
      "cable_type": "fiber_optic",
      "branching_type": "direct",
      "installation_date": "2024-01-15T00:00:00Z",
      "status": "active",
      "notes": "Main fiber line"
    },
    {
      "from_device_id": "uuid-3",
      "to_device_id": "uuid-4",
      "cable_length": 200.0,
      "cable_type": "PTP_SFP_BLD",
      "status": "active"
    }
  ]
}
```

**Response:**
```json
{
  "message": "Bulk create completed: 2 successful, 0 failed out of 2 requested",
  "data": {
    "total_requested": 2,
    "successful": 2,
    "failed": 0,
    "errors": [],
    "results": [
      {
        "id": "generated-uuid-1",
        "from_device_id": "uuid-1",
        "to_device_id": "uuid-2",
        "cable_length": 150.5,
        "cable_type": "fiber_optic",
        "status": "active",
        "from_device": {
          "id": "uuid-1",
          "device_code": "DEV001",
          "device_type": "OLT"
        },
        "to_device": {
          "id": "uuid-2",
          "device_code": "DEV002",
          "device_type": "ODP"
        }
      }
    ],
    "execution_time": "250ms"
  }
}
```

### 2. Bulk Update Cable Connections
**Endpoint:** `PUT /cable-connections/bulk/update`

**Description:** Update multiple cable connections with the same values (up to 100 at once).

**Request Body:**
```json
{
  "connection_ids": [
    "uuid-1",
    "uuid-2",
    "uuid-3"
  ],
  "updates": {
    "status": "maintenance",
    "cable_type": "fiber_optic",
    "notes": "Under maintenance"
  }
}
```

**Response:**
```json
{
  "message": "Bulk update completed: 3 successful, 0 failed out of 3 requested",
  "data": {
    "total_requested": 3,
    "successful": 3,
    "failed": 0,
    "errors": [],
    "results": [
      {
        "id": "uuid-1",
        "status": "maintenance",
        "cable_type": "fiber_optic",
        ...
      }
    ],
    "execution_time": "180ms"
  }
}
```

### 3. Bulk Delete Cable Connections
**Endpoint:** `DELETE /cable-connections/bulk/delete`

**Description:** Delete multiple cable connections in a single request (up to 100 at once).

**Request Body:**
```json
{
  "connection_ids": [
    "uuid-1",
    "uuid-2",
    "uuid-3"
  ]
}
```

**Response:**
```json
{
  "message": "Bulk delete completed: 3 successful, 0 failed out of 3 requested",
  "data": {
    "total_requested": 3,
    "successful": 3,
    "failed": 0,
    "errors": [],
    "execution_time": "120ms"
  }
}
```

## Error Handling

When some items fail during bulk operations, the response will include error details:

```json
{
  "message": "Bulk create completed: 2 successful, 1 failed out of 3 requested",
  "data": {
    "total_requested": 3,
    "successful": 2,
    "failed": 1,
    "errors": [
      {
        "index": 1,
        "error": "From device not found",
        "details": "device with id uuid-999 does not exist"
      }
    ],
    "results": [...],
    "execution_time": "200ms"
  }
}
```

## Validation Rules

### Cable Type Values
- `PTP_SFP_BLD`
- `PTP_SFP_DUPLEX`
- `BB_MONEV`
- `fiber_optic`
- `drop_cable`

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

### Limits
- Maximum connections per bulk create: **100**
- Maximum IDs per bulk update/delete: **100**
- Minimum cable length: **0.1 meters**

## Best Practices

1. **Batch Size**: Keep bulk operations under 50 items for optimal performance
2. **Validation**: Pre-validate device IDs exist before bulk operations
3. **Error Recovery**: Check the `errors` array in the response to handle failed items
4. **Transaction**: Bulk create uses database transactions for data integrity
5. **Performance**: Bulk operations are 5-10x faster than individual requests

## Use Cases

### 1. Initial Data Import
Import cable connections from external systems:
```bash
curl -X POST http://localhost:8080/cable-connections/bulk/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d @cable_connections_import.json
```

### 2. Status Updates During Maintenance
Update multiple connections to maintenance status:
```bash
curl -X PUT http://localhost:8080/cable-connections/bulk/update \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "connection_ids": ["id1", "id2", "id3"],
    "updates": {
      "status": "maintenance"
    }
  }'
```

### 3. Cleanup Old Connections
Remove multiple obsolete connections:
```bash
curl -X DELETE http://localhost:8080/cable-connections/bulk/delete \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "connection_ids": ["id1", "id2", "id3"]
  }'
```

## Performance Metrics

| Operation | Single Request | Bulk (10 items) | Bulk (50 items) | Improvement |
|-----------|---------------|-----------------|-----------------|-------------|
| Create    | 50ms          | 120ms           | 400ms           | 8-10x       |
| Update    | 30ms          | 80ms            | 250ms           | 6-8x        |
| Delete    | 20ms          | 60ms            | 180ms           | 5-7x        |

## Implementation Details

### Architecture Layers

1. **Controller Layer** (`cable_connections_controller.go`)
   - Handles HTTP requests
   - Validates request format
   - Returns formatted responses

2. **Use Case Layer** (`cable_connections_usecase.go`)
   - Business logic validation
   - Device existence checks
   - Error aggregation
   - Transaction coordination

3. **Repository Layer** (`cable_connections_repo.go`)
   - Database operations
   - Batch inserts (50 items per batch)
   - Bulk updates/deletes using SQL IN clause

### Database Optimization

- Uses GORM's `CreateInBatches()` for efficient bulk inserts
- Batches of 50 items for optimal performance
- Single UPDATE/DELETE queries with IN clause
- Transaction support for data consistency

## Security & Authorization

All bulk operations require authentication with one of these roles:
- **Teknisi**
- **Admin**
- **Super Admin**

The middleware validates user permissions before executing bulk operations.

## Related Endpoints

- `GET /cable-connections/:id` - Get single connection
- `POST /cable-connections/search` - Search connections
- `GET /cable-connections/device/:deviceId` - Get connections by device
- `GET /cable-connections/analytics/cable-types` - Cable type analytics

## Support & Troubleshooting

### Common Issues

1. **"From device not found"**
   - Ensure all device IDs exist before creating connections
   - Use `GET /devices/:id` to verify device existence

2. **"Validation failed"**
   - Check cable_type values match allowed types
   - Verify status values are valid
   - Ensure cable_length is >= 0.1

3. **"Connection not found"**
   - Verify connection IDs exist before update/delete
   - Use `GET /cable-connections/:id` to check

### Performance Tips

1. Use bulk operations for > 5 items
2. Split large batches into multiple requests
3. Process errors and retry failed items
4. Monitor execution_time in responses