# Mejoras en el Sistema de Logging - Pedidos Express

## Resumen de Mejoras Implementadas

Este documento describe las mejoras implementadas en el sistema de logging del proyecto Pedidos Express.

## 1. Nuevo Sistema de Logging Estructurado

### Archivo: `services/logging_service.py`

Se implementó un sistema de logging estructurado con las siguientes características:

- **Logging por categorías**: ORDER, USER, PAYMENT, SECURITY, API, DATABASE, EMAIL, PRINT, CHAT, SYSTEM
- **Niveles de log**: DEBUG, INFO, WARNING, ERROR, CRITICAL
- **Logs estructurados en JSON**: Fáciles de procesar y analizar
- **Archivos de log específicos**: Un archivo por categoría para mejor organización
- **Metadatos enriquecidos**: Incluye user_id, user_email, timestamp, datos contextuales

### Funciones principales:
- `log_order_event()`: Para eventos relacionados con pedidos
- `log_user_event()`: Para eventos de usuarios
- `log_security_event()`: Para eventos de seguridad
- `log_api_event()`: Para eventos de API
- `log_database_event()`: Para eventos de base de datos
- `log_email_event()`: Para eventos de email
- `log_print_event()`: Para eventos de impresión
- `log_chat_event()`: Para eventos de chat/LLM
- `log_system_event()`: Para eventos del sistema

## 2. Mejoras por Archivo

### `services/print_service.py`
- ✅ Logging detallado de operaciones de impresión
- ✅ Manejo robusto de errores con contexto
- ✅ Logging de status de impresora
- ✅ Timeouts en requests para evitar bloqueos
- ✅ Logging estructurado para troubleshooting

### `auth/security.py`
- ✅ Logging de eventos de autenticación
- ✅ Logging de generación de tokens
- ✅ Logging de validación de tokens
- ✅ Logging de errores de JWT
- ✅ Logging de intentos de acceso no autorizado

### `services/email_service.py`
- ✅ Logging de conexiones SMTP
- ✅ Logging de autenticación SMTP
- ✅ Logging de envío de emails
- ✅ Logging de reintentos automáticos
- ✅ Logging de errores de conexión

### `routes/orders.py`
- ✅ Logging completo del flujo de pedidos
- ✅ Logging de validaciones de datos
- ✅ Logging de integración con Fudo
- ✅ Logging de creación de ventas
- ✅ Logging de actualización de recompensas
- ✅ Logging de impresión de pedidos
- ✅ Manejo robusto de errores con contexto

### `routes/users.py`
- ✅ Logging de registro de usuarios
- ✅ Logging de intentos de login
- ✅ Logging de bloqueos por intentos fallidos
- ✅ Logging de validaciones RUT
- ✅ Logging de verificaciones por email
- ✅ Logging de eventos de seguridad

### `routes/chat.py`
- ✅ Logging de requests de chat
- ✅ Logging de respuestas de OpenAI
- ✅ Logging de errores de procesamiento
- ✅ Logging de métricas de uso

### `main.py`
- ✅ Logging de inicio de aplicación
- ✅ Logging de validación de configuración
- ✅ Logging de inicialización de componentes
- ✅ Logging de errores críticos de startup

### `app.py`
- ✅ Logging de creación de app FastAPI
- ✅ Logging de configuración de middleware
- ✅ Logging de setup de rutas
- ✅ Logging de montaje de archivos estáticos

## 3. Beneficios del Nuevo Sistema

### Troubleshooting Mejorado
- **Logs estructurados** facilitan el análisis automático
- **Contexto enriquecido** con user_id, emails, datos de request
- **Categorización** permite filtrar por tipo de evento
- **Timestamps precisos** para correlación temporal

### Seguridad
- **Logging de eventos de seguridad** (login failures, admin access attempts)
- **Tracking de intentos de acceso** no autorizado
- **Logging de generación y validación de tokens**

### Monitoreo Operacional
- **Status de servicios externos** (printer, SMTP)
- **Métricas de rendimiento** y tiempo de respuesta
- **Tracking de errores** con stack traces contextuales

### Cumplimiento y Auditoría
- **Trazabilidad completa** de acciones de usuario
- **Logs de transacciones** de pedidos y pagos
- **Registro de accesos administrativos**

## 4. Estructura de Archivos de Log

```
logs/
├── app.log              # Log principal de la aplicación
├── order.log            # Eventos de pedidos
├── user.log             # Eventos de usuarios
├── security.log         # Eventos de seguridad
├── api.log              # Eventos de API
├── database.log         # Eventos de base de datos
├── email.log            # Eventos de email
├── print.log            # Eventos de impresión
├── chat.log             # Eventos de chat/LLM
├── system.log           # Eventos del sistema
├── orders.csv           # Log legacy de pedidos (CSV)
└── llm_responses.txt    # Log legacy de respuestas LLM
```

## 5. Ejemplo de Log Estructurado

```json
{
  "timestamp": "2025-08-07T10:30:15.123456",
  "category": "ORDER",
  "level": "INFO",
  "message": "Order completed successfully for table 5",
  "user_id": 123,
  "user_email": "user@example.com",
  "data": {
    "table": 5,
    "customer_id": 123,
    "total_amount": 25000,
    "items": [
      {"name": "Cerveza", "quantity": 2, "price": 5000},
      {"name": "Hamburguesa", "quantity": 1, "price": 15000}
    ],
    "sale_id": 456,
    "new_reward_progress": 85,
    "beers_for_promo": 2
  }
}
```

## 6. Compatibilidad con Sistema Anterior

- ✅ **Funciones legacy mantenidas** para evitar breaking changes
- ✅ **Archivos CSV y TXT** se siguen generando para compatibilidad
- ✅ **Migración gradual** sin afectar funcionalidad existente

## 7. Recomendaciones de Uso

### Para Desarrollo
- Utilizar nivel `DEBUG` para troubleshooting detallado
- Revisar `logs/security.log` para eventos de autenticación
- Monitorear `logs/print.log` para problemas de impresión

### Para Producción
- Configurar nivel `INFO` o `WARNING` para logs principales
- Implementar rotación de logs para gestión de espacio
- Configurar alertas para eventos `ERROR` y `CRITICAL`
- Monitorear `logs/system.log` para salud de la aplicación

### Para Análisis
- Procesar logs JSON con herramientas como `jq`, ELK stack, o Datadog
- Correlacionar eventos por `user_id` para tracking de usuario
- Analizar métricas de performance y errores

## 8. Próximos Pasos Recomendados

1. **Implementar rotación de logs** con `logrotate` o similar
2. **Configurar alertas** para eventos críticos
3. **Integrar con sistema de monitoreo** (Grafana, Datadog, etc.)
4. **Implementar dashboards** para métricas operacionales
5. **Configurar backup** de logs importantes
6. **Documentar alertas** y procedimientos de respuesta

---

## Comandos Útiles para Análisis de Logs

```bash
# Ver logs de errores en tiempo real
tail -f logs/app.log | grep ERROR

# Analizar logs de seguridad
jq '. | select(.category == "SECURITY")' logs/security.log

# Contar pedidos por usuario
jq '. | select(.category == "ORDER") | .user_email' logs/order.log | sort | uniq -c

# Ver errores de los últimos 30 minutos
jq '. | select(.level == "ERROR" and (.timestamp | fromdateiso8601) > (now - 1800))' logs/app.log
```

Esta implementación proporciona una base sólida para el monitoreo, troubleshooting y análisis operacional del sistema Pedidos Express.