# API Endpoint: Batch Tracking

## Descripción

El endpoint `/api/tracking/batch.php` está diseñado específicamente para manejar múltiples ubicaciones GPS en una sola petición HTTP. Es utilizado por el `BackgroundTrackingService` de la aplicación móvil para enviar ubicaciones acumuladas de manera eficiente.

## URL

```
POST /api/tracking/batch.php
```

## Headers Requeridos

```
Content-Type: application/json
```

## Estructura del Request

```json
{
  "sessionId": "SESSION_1234567890_abc123",
  "vehicleModel": "ANDROID_12.0",
  "locations": [
    {
      "lat": -12.046374,
      "lng": -77.042793,
      "timestamp": 1777190400000,
      "accuracy": 10
    },
    {
      "lat": -12.046500,
      "lng": -77.042900,
      "timestamp": 1777190430000,
      "accuracy": 8
    }
  ]
}
```

### Campos del Request

#### Nivel Principal
- **sessionId** (string, requerido): Identificador único de la sesión de tracking
- **vehicleModel** (string, requerido): Modelo/tipo del dispositivo que está enviando las ubicaciones
- **locations** (array, requerido): Array de ubicaciones GPS

#### Campos de cada Location
- **lat** (number, requerido): Latitud (-90 a 90)
- **lng** (number, requerido): Longitud (-180 a 180)
- **timestamp** (number, requerido): Timestamp en milisegundos
- **accuracy** (number, opcional): Precisión del GPS en metros

## Validaciones

### Validaciones Generales
- ✅ JSON válido
- ✅ Campos requeridos presentes
- ✅ Máximo 1000 ubicaciones por batch
- ✅ Array de locations no vacío

### Validaciones por Ubicación
- ✅ Latitud entre -90 y 90
- ✅ Longitud entre -180 y 180
- ✅ Timestamp numérico válido
- ✅ Timestamp no futuro (tolerancia: 1 minuto)
- ✅ Timestamp no muy antiguo (máximo: 1 año)

## Respuestas

### Éxito (201 Created)

```json
{
  "success": true,
  "message": "Batch procesado: 2 ubicaciones guardadas",
  "data": {
    "sessionId": "SESSION_1234567890_abc123",
    "vehicleModel": "ANDROID_12.0",
    "totalLocations": 2,
    "processedCount": 2,
    "errorCount": 0,
    "locationIds": [123, 124]
  }
}
```

### Éxito Parcial (201 Created)

```json
{
  "success": true,
  "message": "Batch procesado: 1 ubicaciones guardadas, 1 errores encontrados",
  "data": {
    "sessionId": "SESSION_1234567890_abc123",
    "vehicleModel": "ANDROID_12.0",
    "totalLocations": 2,
    "processedCount": 1,
    "errorCount": 1,
    "locationIds": [123],
    "errors": [
      {
        "index": 1,
        "error": "Latitud debe estar entre -90 y 90"
      }
    ]
  }
}
```

### Error de Validación (400 Bad Request)

```json
{
  "success": false,
  "message": "Faltan campos requeridos: sessionId, vehicleModel, locations"
}
```

### Error del Servidor (500 Internal Server Error)

```json
{
  "success": false,
  "message": "Error del servidor: Database connection failed",
  "data": {
    "sessionId": "SESSION_1234567890_abc123",
    "vehicleModel": "ANDROID_12.0",
    "processedCount": 0,
    "errorCount": 0
  }
}
```

## Códigos de Estado HTTP

- **200 OK**: Respuesta a OPTIONS (CORS preflight)
- **201 Created**: Batch procesado exitosamente (al menos 1 ubicación guardada)
- **400 Bad Request**: Error de validación o ninguna ubicación procesada
- **405 Method Not Allowed**: Método HTTP no permitido (solo POST)
- **500 Internal Server Error**: Error del servidor

## Características Especiales

### 🔄 Procesamiento Robusto
- Procesa ubicaciones individualmente
- Continúa procesando aunque algunas fallen
- Reporta errores específicos por ubicación

### 📊 Deduplicación Inteligente
- Detecta ubicaciones duplicadas por timestamp
- Actualiza duración e iteraciones en lugar de duplicar
- Mantiene la ubicación más reciente

### ⚡ Optimización de Performance
- Transacciones de base de datos para consistencia
- Límite de 1000 ubicaciones por batch
- Validaciones eficientes antes de procesar

### 🛡️ Seguridad y Validación
- Validación exhaustiva de coordenadas
- Prevención de timestamps futuros o muy antiguos
- Sanitización de datos de entrada

## Uso con BackgroundTrackingService

El `BackgroundTrackingService` utiliza este endpoint de la siguiente manera:

```typescript
const response = await fetch(`${environment.baseBackendUrl}/api/tracking/batch`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sessionId: this.sessionId,
    vehicleModel: this.deviceModel,
    locations: locations.map(loc => ({
      lat: loc.lat,
      lng: loc.lng,
      timestamp: loc.timestamp || Date.now(),
      accuracy: loc.accuracy
    }))
  })
});
```

## Testing

Para probar el endpoint, ejecuta:

```bash
php test/test_batch_tracking.php
```

Este script ejecuta múltiples casos de prueba incluyendo:
- ✅ Batch válido con múltiples ubicaciones
- ⚠️ Batch con ubicaciones válidas e inválidas
- ❌ Batch vacío
- ❌ Datos requeridos faltantes
- 📦 Batch grande (50 ubicaciones)

## Base de Datos

El endpoint interactúa con las siguientes tablas:

### vehicles
- Almacena información de dispositivos/vehículos
- Se crea automáticamente si no existe

### tracking_sessions
- Almacena sesiones de tracking
- Se crea automáticamente si no existe
- Mantiene contador de puntos totales

### tracking_locations
- Almacena las ubicaciones GPS individuales
- Incluye deduplicación por timestamp
- Mantiene duración e iteraciones para puntos repetidos

## Consideraciones de Producción

### Performance
- Configurar índices apropiados en la base de datos
- Monitorear tiempo de respuesta con batches grandes
- Considerar paginación si se necesitan batches > 1000

### Seguridad
- Implementar autenticación/autorización si es necesario
- Validar origen de las peticiones
- Configurar rate limiting

### Monitoreo
- Logs de errores detallados
- Métricas de ubicaciones procesadas
- Alertas por fallos de procesamiento

---

**✅ Endpoint optimizado para el BackgroundTrackingService y listo para producción.**