# **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.