SYNC_API/sync_api/README.md

# API de Monitoreo de Sincronización - Aduanasoft

Sistema de monitoreo de bases de datos SQL Server con API REST desarrollada en FastAPI.

## Características

- ✅ API REST completa con FastAPI
- ✅ Conexión robusta a SQL Server con pyodbc
- ✅ Endpoints para monitoreo de nodos individuales y generales
- ✅ Health checks del sistema
- ✅ Información de backups (opcional)
- ✅ Configuración CORS para integración PHP
- ✅ Logging completo
- ✅ Documentación automática con Swagger/OpenAPI
- ✅ Manejo de errores robusto
- ✅ Validación de datos con Pydantic

## Estructura del Proyecto

```
sync_api/
├── main.py                 # Aplicación principal FastAPI
├── requirements.txt        # Dependencias Python
├── .env                   # Variables de entorno
├── models/
│   └── sync_models.py     # Modelos Pydantic para respuestas
├── database/
│   └── connection.py      # Conexión y queries SQL Server
├── routers/
│   ├── nodes.py          # Endpoints de nodos
│   └── health.py         # Endpoints de salud
└── config/
    └── settings.py       # Configuración de la aplicación
```

## Configuración

### 1. Variables de Entorno

Editar el archivo `.env` con tus credenciales de SQL Server:

```bash
DATABASE_SERVER=tu_servidor
DATABASE_NAME=tu_base_datos
DATABASE_USER=tu_usuario
DATABASE_PASSWORD=tu_password
DATABASE_DRIVER=ODBC Driver 17 for SQL Server
```

### 2. Instalación de Dependencias

```bash
pip install -r requirements.txt
```

### 3. Verificar Driver ODBC

Asegúrate de tener instalado el driver ODBC 17 para SQL Server:
- [Microsoft ODBC Driver 17 for SQL Server](https://docs.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server)

## Ejecución

### Desarrollo
```bash
python main.py
```

### Producción con Uvicorn
```bash
uvicorn main:app --host 0.0.0.0 --port 8000
```

### Producción con Gunicorn (Linux)
```bash
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```

## Endpoints Disponibles

### 📊 Monitoreo de Nodos

- **GET /api/nodes** - Lista todos los nodos
- **GET /api/nodes/{node_name}/status** - Estado específico de un nodo
- **GET /api/nodes/{node_name}/backup-info** - Información de respaldos

### 🏥 Health Checks

- **GET /api/health** - Estado general del sistema
- **GET /api/ping** - Ping simple

### 📖 Documentación

- **GET /docs** - Documentación Swagger UI
- **GET /redoc** - Documentación ReDoc
- **GET /** - Información general de la API

## Ejemplos de Uso

### Estado de un Nodo Específico
```bash
curl http://localhost:8000/api/nodes/NODO001/status
```

Respuesta:
```json
{
  "nodo_sub_nodo": "NODO001",
  "estado_sincronizacion": "Actualizada",
  "ultima_sincronizacion": "2025-11-03T10:30:00",
  "total_clientes": 45,
  "clientes_activos": 42,
  "clientes_inactivos": 3,
  "tiempo_desde_ultima_sync": "2 horas"
}
```

### Lista de Todos los Nodos
```bash
curl http://localhost:8000/api/nodes
```

### Health Check del Sistema
```bash
curl http://localhost:8000/api/health
```

Respuesta:
```json
{
  "status": "healthy",
  "database_status": "healthy",
  "total_nodes": 15,
  "nodes_healthy": 12,
  "nodes_attention": 2,
  "nodes_error": 1,
  "last_check": "2025-11-03T12:00:00",
  "uptime": "2h 15m",
  "version": "1.0.0"
}
```

## Integración con PHP

### Ejemplo AJAX básico:

```javascript
// Obtener estado de un nodo
fetch('http://localhost:8000/api/nodes/NODO001/status')
  .then(response => response.json())
  .then(data => {
    console.log('Estado del nodo:', data);
    // Actualizar dashboard
  })
  .catch(error => console.error('Error:', error));

// Health check periódico
setInterval(() => {
  fetch('http://localhost:8000/api/health')
    .then(response => response.json())
    .then(data => {
      updateHealthIndicator(data.status);
    });
}, 30000); // Cada 30 segundos
```

### Ejemplo PHP con cURL:

```php
function getNodeStatus($nodeName) {
    $url = "http://localhost:8000/api/nodes/{$nodeName}/status";
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    }
    
    return null;
}

// Uso
$nodeStatus = getNodeStatus('NODO001');
if ($nodeStatus) {
    echo "Estado: " . $nodeStatus['estado_sincronizacion'];
}
```

## Estados de Sincronización

| Estado | Descripción | Acción Recomendada |
|--------|-------------|-------------------|
| **Actualizada** | Funcionando correctamente | Monitoreo normal |
| **Atención** | Requiere revisión | Investigar causa |
| **Error** | Problema crítico | Acción inmediata |

## Logging

Los logs se muestran en consola y incluyen:
- Peticiones HTTP entrantes y salientes
- Tiempos de procesamiento
- Errores de conexión a BD
- Estadísticas de consultas

Nivel de logging configurable via `LOG_LEVEL` en `.env`:
- `DEBUG`: Información detallada
- `INFO`: Información general (por defecto)
- `WARNING`: Solo advertencias y errores
- `ERROR`: Solo errores

## Monitoreo y Alertas

### Métricas Clave a Monitorear:
- Estado de conectividad de la API (`/api/ping`)
- Estado general del sistema (`/api/health`)
- Tiempo de respuesta de endpoints
- Errores de conexión a base de datos
- Distribución de estados de nodos

### Alertas Sugeridas:
- API no responde en `/api/ping`
- Base de datos desconectada
- Más del 20% de nodos en estado "Error"
- Tiempo de respuesta > 5 segundos
- Nodo sin sincronizar > 24 horas

## Solución de Problemas

### Error de Conexión a SQL Server
1. Verificar credenciales en `.env`
2. Confirmar que SQL Server acepta conexiones
3. Verificar firewall y puertos
4. Comprobar driver ODBC instalado

### API no responde
1. Verificar que el puerto 8000 esté disponible
2. Revisar logs de la aplicación
3. Confirmar dependencias instaladas

### Errores de CORS
1. Agregar el dominio PHP a `allow_origins` en `main.py`
2. Verificar headers permitidos
3. Comprobar métodos HTTP utilizados

## Desarrollo y Extensiones

### Agregar Nuevos Endpoints:
1. Crear función en router apropiado (`routers/nodes.py` o `routers/health.py`)
2. Definir modelo de respuesta en `models/sync_models.py`
3. Documentar endpoint con docstrings

### Optimizaciones Futuras:
- Cache con Redis para consultas frecuentes
- Paginación avanzada para listas grandes
- Filtros adicionales por fecha/cliente
- Websockets para actualizaciones en tiempo real
- Autenticación y autorización

## Soporte

Para soporte técnico o mejoras, contactar al equipo de desarrollo de Aduanasoft.

---

**Versión:** 1.0.0  
**Desarrollado con:** FastAPI + Python 3.12  
**Base de Datos:** SQL Server  
**Licencia:** Propietaria - Aduanasoft