# Biergarten Klein - Sistema de Pedidos Express

## Descripción del Proyecto

**Biergarten Klein** es una aplicación web completa para la gestión de pedidos en un bar cervecero artesanal. El sistema permite a los clientes interactuar con un asistente de IA llamado "Camilo Klein" para consultar el menú, recibir recomendaciones de cervezas artesanales, realizar pedidos y gestionar su experiencia en el establecimiento.

## Características Principales

### 🤖 Asistente de IA Personalizado
- **Camilo Klein**: Chatbot especializado en el menú del bar
- Integración con OpenAI GPT-4o-mini
- Respuestas carismáticas con emojis
- Base de conocimientos específica sobre cervezas artesanales
- Sistema anti-abuso con tokens de sesión

### 🍺 Gestión de Productos
- Catálogo completo de cervezas artesanales (Burlesque, Queen Burlesque, Hoppy Mosh, Black Mamba, etc.)
- Sistema de carrito de compras interactivo
- Información detallada de cada cerveza (IBU, SRM, notas de sabor)
- Precios y disponibilidad en tiempo real

### 🧾 Sistema de Pedidos
- Procesamiento de pedidos con validación
- Integración con impresora térmica USB
- Sincronización con sistema Fudo POS
- Notificaciones por email en caso de errores
- Logging completo de transacciones

### 🔐 Seguridad y Autenticación
- Sistema de tokens anti-abuso
- Validación de usuarios
- Protección de endpoints sensibles
- Middleware de sesiones seguras

## Estructura del Proyecto

```
pedidos_express/
├── main.py                    # Punto de entrada principal
├── app.py                     # Configuración FastAPI y rutas
├── requirements.txt           # Dependencias del proyecto
├── tailwind.config.js         # Configuración de Tailwind CSS
├── config/
│   ├── __init__.py
│   └── settings.py           # Variables de entorno y logging
├── models/
│   ├── __init__.py
│   └── schemas.py            # Modelos Pydantic (Message, Order, User)
├── auth/
│   ├── __init__.py
│   └── security.py           # Autenticación y tokens anti-abuso
├── services/
│   ├── __init__.py
│   ├── data_service.py       # Gestión de datos y productos
│   ├── openai_service.py     # Integración con OpenAI
│   ├── email_service.py      # Notificaciones por email
│   ├── fudo_service.py       # Integración con Fudo POS
│   └── logging_service.py    # Sistema de logs
├── routes/
│   ├── __init__.py
│   ├── chat.py              # Endpoints del chatbot
│   ├── users.py             # Gestión de usuarios
│   ├── products.py          # Catálogo de productos
│   ├── orders.py            # Procesamiento de pedidos
│   └── static.py            # Archivos estáticos
├── impresora/               # Módulo de impresión térmica
│   ├── __init__.py
│   ├── order.py             # Modelos para órdenes de impresión
│   └── printer.py           # Control de impresora USB
├── fudo/                    # Integración con Fudo POS
│   └── fudo.py              # API y gestión de tokens
├── data/                    # Almacenamiento de datos
│   ├── data.db              # Base de datos SQLite
│   ├── llm_data.json        # Base de conocimientos para IA
│   └── products.json        # Catálogo de productos
├── public/                  # Frontend web
│   ├── index.html           # Página principal
│   ├── styles.css           # Estilos personalizados
│   ├── assets/              # Recursos multimedia
│   └── js/
│       ├── app.js           # Lógica principal del frontend
│       ├── interfaces.js    # Interfaces de usuario
│       └── service/         # Servicios del frontend
│           ├── auth.js      # Autenticación cliente
│           ├── chat.js      # Comunicación con chatbot
│           └── product.js   # Gestión de productos
└── logs/                    # Archivos de log
    └── app.log              # Logs de la aplicación
```

## Tecnologías Utilizadas

### Backend
- **FastAPI**: Framework web moderno y rápido
- **Python 3.9+**: Lenguaje de programación principal
- **OpenAI API**: Integración con GPT-4o-mini para el chatbot
- **SQLite**: Base de datos local
- **Redis**: Cache para tokens de autenticación
- **Uvicorn**: Servidor ASGI para producción

### Frontend
- **HTML5/CSS3/JavaScript**: Tecnologías web estándar
- **Tailwind CSS**: Framework de estilos utilitarios
- **Vanilla JavaScript**: Sin frameworks adicionales para máximo rendimiento

### Integraciones
- **Fudo POS**: Sistema de punto de venta
- **Impresora Térmica USB**: Para tickets de pedidos
- **SMTP**: Envío de notificaciones por email

## Módulos Principales

### config/settings.py
- Configuración centralizada de la aplicación
- Gestión de variables de entorno
- Sistema de logging configurado
- Validación de configuración crítica

### models/schemas.py
- **Message**: Estructura para mensajes del chat
- **ChatCompletionRequest**: Requests para el chatbot
- **OrderWeb**: Modelo completo de pedidos
- **ItemWeb**: Elementos individuales del pedido
- **UserCodeRequest**: Validación de códigos de usuario

### auth/security.py
- **Sistema de tokens anti-abuso**: Protección contra uso excesivo
- **Validación de sesiones**: Control de acceso a endpoints
- **Middleware de seguridad**: Protección de rutas sensibles
- **Generación segura de tokens**: Utilizando secrets

### services/
- **data_service.py**: Carga y gestión de productos, usuarios y datos del menú
- **openai_service.py**: Integración completa con OpenAI para el asistente Camilo Klein
- **email_service.py**: Sistema de notificaciones por correo electrónico
- **fudo_service.py**: Integración bidireccional con el sistema Fudo POS
- **logging_service.py**: Registro detallado de pedidos y respuestas del LLM

### routes/
- **chat.py**: 
  - `/api/chat/init-chat` - Inicialización del chat y generación de tokens
  - `/api/chat/completions` - Procesamiento de mensajes del chatbot
- **users.py**: 
  - `/api/existsUser` - Validación de códigos de usuario
- **products.py**: 
  - `/api/get_products` - Obtención del catálogo completo
- **orders.py**: 
  - `/api/printer/order` - Procesamiento e impresión de pedidos
- **static.py**: 
  - Servir archivos estáticos y página principal

## API Endpoints

### Chat y Asistente IA
```
GET  /api/chat/init-chat       # Inicializar sesión de chat
POST /api/chat/completions     # Enviar mensaje al asistente
```

### Gestión de Productos
```
GET  /api/get_products         # Obtener catálogo de productos
```

### Gestión de Pedidos
```
POST /api/printer/order        # Procesar y imprimir pedido
```

### Usuarios
```
POST /api/existsUser          # Validar código de usuario
```

## Flujo de la Aplicación

1. **Inicialización**: El usuario accede a la página principal
2. **Autenticación**: Se genera un token anti-abuso para la sesión
3. **Exploración**: El usuario puede consultar productos y chatear con Camilo Klein
4. **Pedido**: Selección de productos y agregado al carrito
5. **Procesamiento**: Validación, impresión y sincronización con Fudo POS
6. **Confirmación**: Notificación al usuario y registro en logs

## Base de Conocimientos del Asistente

El asistente Camilo Klein utiliza una base de datos especializada (`llm_data.json`) que incluye:

- **Información del establecimiento**: Historia y concepto del Biergarten Klein
- **Catálogo completo de cervezas**: 15+ variedades artesanales con detalles técnicos
- **Recomendaciones especializadas**: Sugerencias basadas en preferencias
- **Información nutricional y técnica**: IBU, SRM, graduación alcohólica
- **Horarios y ubicación**: Datos prácticos para los clientes

## Características Técnicas Avanzadas

### Sistema de Logging
- Registro detallado de todas las interacciones
- Logs estructurados con timestamps
- Separación por niveles (INFO, WARNING, ERROR)
- Rotación automática de archivos de log

### Integración con Hardware
- **Impresora térmica USB**: Detección automática y manejo de errores
- **Códigos de barras**: Generación para tracking de pedidos
- **Notificaciones automáticas**: Email en caso de fallos de hardware

### Gestión de Estado
- **Redis para cache**: Tokens de autenticación y sesiones
- **SQLite para persistencia**: Datos permanentes y históricos
- **JSON para configuración**: Datos del menú y configuraciones

## Ventajas de la Arquitectura

1. **Modularidad**: Cada componente tiene responsabilidades específicas
2. **Escalabilidad**: Fácil agregar nuevas funcionalidades
3. **Mantenibilidad**: Código organizado y bien documentado
4. **Testabilidad**: Componentes aislados para pruebas unitarias
5. **Seguridad**: Múltiples capas de protección
6. **Performance**: Optimizado para respuestas rápidas

## Instalación y Configuración

### Prerequisitos
```bash
Python 3.9+
Redis Server
Impresora térmica USB (opcional)
```

### Instalación
```bash
# Clonar el repositorio
git clone [repository-url]
cd pedidos_express

# Instalar dependencias
pip install -r requirements.txt

# Configurar variables de entorno
cp .env.example .env
```

### Variables de Entorno Requeridas
```env
# OpenAI Configuration
OPENAI_API_KEY=tu_api_key_de_openai

# Security
SECRET_KEY=tu_clave_secreta_muy_segura

# Server Configuration  
PORT=6001
LOG_LEVEL=INFO

# Fudo POS Integration
FUDO_API_KEY=tu_api_key_fudo
FUDO_API_SECRET=tu_api_secret_fudo

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0

# Email Configuration (opcional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=tu_email@gmail.com
SMTP_PASSWORD=tu_password_de_app
```

## Ejecución

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

### Producción
```bash
gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app --bind 0.0.0.0:6001
```

## Monitoreo y Logs

### Archivos de Log
- `logs/app.log`: Log principal de la aplicación
- `logs.csv`: Registro de interacciones del LLM

### Métricas Monitoreadas
- Tiempo de respuesta del chatbot
- Errores de impresión
- Fallos de conexión con Fudo POS
- Uso del sistema anti-abuso

## Seguridad

### Medidas Implementadas
- **Tokens anti-abuso**: Prevención de spam y uso excesivo
- **Validación de entrada**: Sanitización de todos los inputs
- **Protección CSRF**: Tokens de sesión seguros
- **Rate limiting**: Control de frecuencia de requests
- **Logging de seguridad**: Registro de intentos de acceso no autorizado

## Desarrollo y Contribución

### Estructura de Commits
- `feat:` Nuevas características
- `fix:` Corrección de bugs  
- `docs:` Documentación
- `style:` Formateo de código
- `refactor:` Refactorización
- `test:` Pruebas

### Testing
```bash
# Ejecutar tests unitarios
python -m pytest tests/

# Tests de integración
python -m pytest tests/integration/
```

## Roadmap Futuro

### Próximas Características
- [ ] Sistema de reservas de mesas
- [ ] Programa de fidelización
- [ ] Integración con redes sociales
- [ ] App móvil nativa
- [ ] Dashboard de analytics
- [ ] Sistema de reviews y ratings

### Mejoras Técnicas
- [ ] Migración a PostgreSQL
- [ ] Implementación de microservicios
- [ ] Containerización con Docker
- [ ] CI/CD con GitHub Actions
- [ ] Monitoreo con Prometheus

## Soporte y Contacto

Para soporte técnico o consultas sobre el proyecto, contactar al equipo de desarrollo.

---

**Versión**: 1.0.0  
**Última actualización**: Julio 2025  
**Licencia**: Privada - Biergarten Klein