|
|
@@ -1,94 +1,348 @@
|
|
|
-# Web Pedidos Klein - Backend
|
|
|
+# Biergarten Klein - Sistema de Pedidos Express
|
|
|
|
|
|
-## Estructura del Proyecto
|
|
|
+## 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
|
|
|
|
|
|
-El backend ha sido reorganizado para mejorar la mantenibilidad y seguir buenas prácticas de desarrollo. La nueva estructura es:
|
|
|
+### 🧾 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 de la aplicación FastAPI
|
|
|
-├── requirements.txt # Dependencias
|
|
|
-├── .env # Variables de entorno
|
|
|
+├── 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 # Configuración y variables de entorno
|
|
|
+│ └── settings.py # Variables de entorno y logging
|
|
|
├── models/
|
|
|
│ ├── __init__.py
|
|
|
-│ └── schemas.py # Modelos Pydantic
|
|
|
+│ └── schemas.py # Modelos Pydantic (Message, Order, User)
|
|
|
├── auth/
|
|
|
│ ├── __init__.py
|
|
|
-│ └── security.py # Autenticación y seguridad
|
|
|
+│ └── security.py # Autenticación y tokens anti-abuso
|
|
|
├── services/
|
|
|
│ ├── __init__.py
|
|
|
-│ ├── data_service.py # Manejo de datos (productos, usuarios)
|
|
|
-│ ├── openai_service.py # Servicio de OpenAI/ChatGPT
|
|
|
-│ ├── email_service.py # Servicio de envío de emails
|
|
|
-│ ├── fudo_service.py # Integración con Fudo
|
|
|
-│ └── logging_service.py # Logging de pedidos y respuestas
|
|
|
+│ ├── 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 chat
|
|
|
-│ ├── users.py # Endpoints de usuarios
|
|
|
-│ ├── products.py # Endpoints de productos
|
|
|
-│ ├── orders.py # Endpoints de pedidos
|
|
|
+│ ├── 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 (existente)
|
|
|
-├── fudo/ # Módulo Fudo (existente)
|
|
|
-└── public/ # Archivos estáticos frontend
|
|
|
+├── 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
|
|
|
```
|
|
|
|
|
|
-## Módulos
|
|
|
+## 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 de la aplicación
|
|
|
-- Variables de entorno
|
|
|
-- Validación de configuración
|
|
|
+- 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
|
|
|
-- Modelos Pydantic para request/response
|
|
|
-- Validación de datos
|
|
|
+- **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
|
|
|
-- Middleware de autenticación
|
|
|
-- Generación de tokens anti-abuse
|
|
|
-- Protección de endpoints
|
|
|
+- **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 manejo de datos (productos, usuarios, datos del menú)
|
|
|
-- **openai_service.py**: Integración con OpenAI para el chatbot
|
|
|
-- **email_service.py**: Envío de notificaciones por email
|
|
|
-- **fudo_service.py**: Integración con el sistema Fudo
|
|
|
-- **logging_service.py**: Logging de pedidos y respuestas del LLM
|
|
|
+- **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**: Endpoints relacionados con el chat (/api/chat/*)
|
|
|
-- **users.py**: Endpoints de usuarios (/api/existsUser)
|
|
|
-- **products.py**: Endpoints de productos (/api/get_products)
|
|
|
-- **orders.py**: Endpoints de pedidos (/api/printer/order)
|
|
|
-- **static.py**: Servir archivos estáticos
|
|
|
+- **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 Nueva Estructura
|
|
|
+## Ventajas de la Arquitectura
|
|
|
|
|
|
-1. **Separación de responsabilidades**: Cada módulo tiene una función específica
|
|
|
-2. **Mantenibilidad**: Código más fácil de mantener y modificar
|
|
|
-3. **Testabilidad**: Cada módulo puede ser probado independientemente
|
|
|
-4. **Escalabilidad**: Fácil agregar nuevas funcionalidades
|
|
|
-5. **Legibilidad**: Código más organizado y fácil de entender
|
|
|
+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
|
|
|
|
|
|
-## Cómo Ejecutar
|
|
|
+## Instalación y Configuración
|
|
|
|
|
|
+### Prerequisitos
|
|
|
```bash
|
|
|
-python main.py
|
|
|
+Python 3.9+
|
|
|
+Redis Server
|
|
|
+Impresora térmica USB (opcional)
|
|
|
```
|
|
|
|
|
|
-## Variables de Entorno Requeridas
|
|
|
+### 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_API_KEY=tu_api_key_aqui
|
|
|
-SECRET_KEY=tu_secret_key_para_sessions
|
|
|
+# 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
|