pedidos-express

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.