# **Biergarten Klein \- Sistema de Pedidos Express** Este proyecto es el backend de una aplicación web de gestión de pedidos para el bar cervecero artesanal **Biergarten Klein**. Está construido con **FastAPI** y proporciona una API RESTful para gestionar productos, pedidos, usuarios y un asistente de IA ("Camilo Klein") basado en OpenAI. ## **🚀 Puesta en Marcha (Getting Started)** Sigue estos pasos para levantar el entorno de desarrollo local. ### **1\. Prerrequisitos** * **Python 3.9+** * **Servidor Redis** (para la gestión de tokens y sesiones) * (Opcional) Una impresora térmica USB configurada en el sistema. ### **2\. Instalación** 1. Clona el repositorio: git clone \[repository-url\] cd pedidos\_express\_server 2. Crea y activa un entorno virtual (recomendado): python \-m venv venv source venv/bin/activate \# En Windows: venv\\Scripts\\activate 3. Instala las dependencias: pip install \-r requirements.txt 4. Configura las variables de entorno. Crea un archivo .env en la raíz del proyecto basándote en el archivo .env.example (o el .env proporcionado si ya lo tienes). ### **3\. Variables de Entorno (.env)** Asegúrate de que tu archivo .env contenga las siguientes claves: \# \--- Configuración del Servidor \--- PORT=6001 LOG\_LEVEL=INFO \# \--- Seguridad (¡Genera claves seguras\!) \--- SECRET\_KEY=tu\_clave\_secreta\_muy\_segura \# \--- OpenAI API \--- OPENAI\_API\_KEY=tu\_api\_key\_de\_openai \# \--- Redis \--- REDIS\_HOST=localhost REDIS\_PORT=6379 REDIS\_DB=0 \# \--- Fudo POS \--- FUDO\_API\_KEY=tu\_api\_key\_fudo FUDO\_API\_SECRET=tu\_api\_secret\_fudo \# \--- Email (para notificaciones de error) \--- SMTP\_HOST=smtp.gmail.com SMTP\_PORT=587 SMTP\_USER=tu\_email@gmail.com SMTP\_PASSWORD=tu\_password\_de\_app ### **4\. Ejecución** #### **Modo Desarrollo** Ejecuta el servidor con Uvicorn para recarga automática (como se define en main.py): python main.py La aplicación estará disponible en http://localhost:6001. #### **Modo Producción** Usa Gunicorn para gestionar los workers de Uvicorn: gunicorn \-w 4 \-k uvicorn.workers.UvicornWorker app:app \--bind 0.0.0.0:6001 ## **🏗️ Resumen de la Arquitectura** El proyecto sigue una arquitectura modular separando la configuración, la lógica de negocio, las rutas y los modelos de datos. * **main.py**: Punto de entrada principal. Inicia el servidor Uvicorn leyendo la configuración. * **app.py**: Corazón de la aplicación FastAPI. Aquí se configuran los middlewares (CORS, NoCache), se montan las rutas (routers) y se define la lógica de inicio. * **config/**: Contiene la configuración centralizada. * settings.py: Carga las variables de entorno (.env) usando Pydantic. * messages.py: Mensajes de sistema para el chatbot. * mails.py: Plantillas para correos de notificación. * **models/**: Define los esquemas de datos (Pydantic) usados en la API para validación y serialización (chat.py, items.py, user.py, sales.py). * **routes/**: Define los *routers* de FastAPI (endpoints de la API). Cada archivo agrupa endpoints por funcionalidad (chat.py, orders.py, products.py, users.py, sales.py). * static.py: Sirve los archivos del frontend (public/). * **services/**: Contiene la lógica de negocio principal, desacoplada de las rutas. * data\_service.py: Gestiona la carga de datos (productos, usuarios) desde archivos JSON. * openai\_service/: Lógica para interactuar con la API de OpenAI, incluyendo la gestión de herramientas (tools). * fudo\_service.py: Lógica para la integración con el POS Fudo. * print\_service.py: Lógica para interactuar con la impresora térmica USB. * email\_service.py: Envío de notificaciones por email. * recovery\_service.py: Lógica para recuperación de acceso. * **auth/**: Lógica de seguridad. * security.py: Generación y validación de tokens (anti-abuso, sesiones). * **middleware/**: Middlewares personalizados de FastAPI. * no\_cache.py: Asegura que las respuestas de la API no se almacenen en caché. * in\_time.py: (Posiblemente) valida si las operaciones se realizan en horario comercial. * **utils/**: Funciones de utilidad reutilizables. * responses.py: Constructores de respuestas HTTP estandarizadas. * rut.py: Utilidades para validación de RUT. * **data/**: Almacenamiento de datos estáticos. * products.json: Catálogo de productos y cervezas. * llm\_data.json: Base de conocimientos específica para el asistente de IA. * **public/**: Contiene el frontend (cliente web estático) en Vanilla JS, HTML y CSS. * **logs/**: Directorio donde se escriben los logs de la aplicación (ej. app.log). ## **🤖 Características Principales** ### **Asistente de IA (Camilo Klein)** * Integración con **OpenAI GPT-4o-mini** (services/openai\_service). * Base de conocimientos personalizada (data/llm\_data.json). * Sistema de "tools" de OpenAI para interactuar con el catálogo de productos. * Sistema de tokens anti-abuso para proteger el endpoint (auth/security.py). ### **Gestión de Pedidos y Productos** * Catálogo de productos cargado desde products.json (services/data\_service.py). * Carrito de compras gestionado en el frontend (public/main/js/utils/shoppingCart.js). * Procesamiento de pedidos (routes/orders.py). ### **Integraciones de Hardware y Externas** * **Impresora Térmica USB**: El print\_service.py se encarga de formatear y enviar los pedidos a la impresora. * **Fudo POS**: Sincronización de pedidos con el sistema de punto de venta (services/fudo\_service.py). * **Email**: Notificaciones de error o críticas del sistema (services/email\_service.py). ### **Seguridad** * **Tokens anti-abuso**: Se genera un token al iniciar el chat (/api/chat/init-chat) que debe usarse para todas las peticiones de chat (/api/chat/completions). * **Validación de Sesión**: Protección de endpoints sensibles. * **Variables de Entorno**: No hay claves quemadas en el código; todo se gestiona vía config/settings.py. ## **🔌 API Endpoints (Resumen)** Consulta los archivos en routes/ para ver la definición completa, incluyendo los modelos de request y response. ### **Chat (Asistente IA)** * GET /api/chat/init-chat: Inicia una sesión de chat y obtiene un token anti-abuso. * POST /api/chat/completions: Envía un mensaje al asistente (requiere token). ### **Productos** * GET /api/get\_products: Obtiene el catálogo completo de productos. ### **Pedidos** * POST /api/printer/order: Recibe una orden, la procesa, la imprime y la envía a Fudo. ### **Usuarios** * POST /api/existsUser: Valida la existencia de un código de usuario/mesa. * *(Otros endpoints de autenticación y registro en routes/users.py)*. ### **Ventas (Sales)** * *(Endpoints definidos en routes/sales.py para gestionar ventas)*. ### **Frontend** * GET /: Sirve el index.html principal (public/main/index.html). * GET /register: Sirve la página de registro. * GET /verify: Sirve la página de verificación. * *(Rutas estáticas para js, css, assets)*. ## **🛠️ Tecnologías Utilizadas** * **Backend**: FastAPI, Python 3.9+ * **Servidor ASGI**: Uvicorn, Gunicorn * **Frontend**: Vanilla JavaScript (ES6+), Tailwind CSS, HTML5 * **Base de Datos (Estado/Caché)**: Redis * **Base de Datos (Datos Estáticos)**: Archivos JSON * **IA**: OpenAI API (GPT-4o-mini) * **Integraciones**: Fudo POS (API REST), Impresora Térmica (USB), SMTP ## **📝 Logging y Monitoreo** * El logging está configurado en config/settings.py. * Los logs de la aplicación se escriben por defecto en logs/app.log. * Se registran eventos críticos como errores de impresión, fallos en la API de Fudo y errores inesperados del servidor.