pedidos-express

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

Python 3.9+
Redis Server
Impresora térmica USB (opcional)

Instalación

# 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

# 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

python main.py

Producción

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

# 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