Initial commit: SYNC_API project
This commit is contained in:
274
sync_api/README.md
Normal file
274
sync_api/README.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user