Bienvenido a la guía general de Capybara Films, donde vas a encontrar una explicación clara de cómo está construido este sistema, cuáles son sus partes principales, y cómo se relacionan entre sí para permitir la gestión de un cine desde la consola.

Esta guía está pensada para ayudarte a entender los fundamentos del sistema, tanto si eres un desarrollador como si simplemente quieres conocer cómo funciona todo "por dentro".

• 🏗️ Arquitectura General del Sistema
  • 🧱 Explicación por Capas
• 🧭 Flujo Principal del Sistema
  • 🔍 Explicación Paso a Paso del Flujo
• 🧩 Componentes y Funcionalidades
• 📋 Validaciones y Reglas de Negocio
• 💻 Tecnologías Utilizadas
  • 🔧 Detalles de Tecnologías y Patrones
• ⚠️ Manejo de Errores

Capybara Films está construido siguiendo una arquitectura por capas, lo que significa que cada parte del sistema tiene una responsabilidad clara y separada. Esto ayuda a mantener el código ordenado, más fácil de mantener y expandir en el futuro.

En este proyecto se aplica el patrón DAO (Data Access Object), que permite separar el acceso a la base de datos del resto de la lógica del programa. También se usa una base de datos PostgreSQL para guardar toda la información relacionada a clientes, películas, reservas, etc.

El siguiente diagrama muestra cómo se relacionan las distintas capas del sistema:

graph TD
    subgraph **Capa de Presentación**
        A[🎬 main.py]
    end

    subgraph **Capa de Servicios**
        B[CineServices]
        C[ServicioValidacion]
    end

    subgraph **Capa de Acceso a Datos**
        D[📂 ClienteDAO]
        E[📂 PeliculaDAO]
        F[📂 SalaDAO]
        G[📂 ButacaDAO]
        H[📂 ReservaDAO]
        I[📂 CandyDAO]
    end

    subgraph **Capa de Persistencia**
        J[🛢️ DatabaseConnection]
        K[(PostgreSQL)]
    end

    A --> B
    A --> C
    B --> D
    B --> E
    B --> F
    B --> G
    B --> H
    B --> I
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    J --> K

1. Capa de Presentación

• Contiene main.py
• Es el punto de entrada de la app: recibe la interacción del usuario y comienza el flujo de reserva.

2. Capa de Servicios y Validaciones

• CineServices coordina todo el proceso: seleccionar película, butaca, combos, etc.
• ServicioValidacion se encarga de validar datos como el DNI o los campos vacíos.

3. Capa de Acceso a Datos (DAOs)

• Los DAO son responsables de comunicarse con la base de datos:
  • ClienteDAO, PeliculaDAO, SalaDAO, etc.
• Cada uno sabe cómo acceder, insertar o modificar sus entidades.

4. Capa de Persistencia

• DatabaseConnection gestiona las conexiones reales con la base de datos.
• La base de datos utilizada es PostgreSQL.

Ahora que ya vimos cómo se organiza el sistema internamente a nivel de arquitectura, veamos cómo fluye el sistema cuando un usuario realiza una reserva completa desde la consola.

Este flujo describe las acciones que se ejecutan en orden dentro de main.py, interactuando con los distintos servicios, DAOs y entidades del sistema. Se trata del recorrido completo, desde que se inicia la aplicación hasta que se genera el resumen final de la compra.

El siguiente diagrama muestra los pasos clave del proceso:

graph TD
    A[🎬 <b>main.py</b><br>Punto de entrada] --> B[1️⃣ <b>Verificar Cliente</b><br>ServicioValidacion]
    B --> B1[[📂 ClienteDAO]]

    B --> C[2️⃣ <b>Elegir Película</b><br>CineServices]
    C --> C1[[📂 PeliculaDAO]]

    C --> D[3️⃣ <b>Seleccionar Sala y Entradas</b><br>CineServices]
    D --> D1[[📂 SalaDAO]]

    D --> E[4️⃣ <b>Seleccionar Butacas</b><br>CineServices]
    E --> E1[[📂 ButacaDAO]]

    E --> F[5️⃣ <b>Crear Reserva</b><br>CineServices]
    F --> F1[[📂 ReservaDAO]]

    F --> G[6️⃣ <b>Seleccionar Combos</b><br>CineServices]
    G --> G1[[📂 CandyDAO]]

    G --> H[7️⃣ <b>Mostrar Resumen</b><br>Reserva]

    %% Estilos
    style A fill:#ffdd88,stroke:#333,color:#000
    style B fill:#b3d9ff,stroke:#333,color:#000
    style C fill:#b3d9ff,stroke:#333,color:#000
    style D fill:#b3d9ff,stroke:#333,color:#000
    style E fill:#b3d9ff,stroke:#333,color:#000
    style F fill:#b3d9ff,stroke:#333,color:#000
    style G fill:#b3d9ff,stroke:#333,color:#000
    style H fill:#b3d9ff,stroke:#333,color:#000

    style B1 fill:#e6f0ff,stroke:#666,color:#000
    style C1 fill:#e6f0ff,stroke:#666,color:#000
    style D1 fill:#e6f0ff,stroke:#666,color:#000
    style E1 fill:#e6f0ff,stroke:#666,color:#000
    style F1 fill:#e6f0ff,stroke:#666,color:#000
    style G1 fill:#e6f0ff,stroke:#666,color:#000

• 1️⃣ Verificar Cliente: Se valida si el cliente ya está registrado usando ServicioValidacion y ClienteDAO. Si no lo está, se le solicita registrarse.

• 2️⃣ Elegir Película: El usuario selecciona una película de la cartelera. Se consulta a través de PeliculaDAO.

• 3️⃣ Seleccionar Sala y Entradas: Se muestra la sala disponible para la película y se pide la cantidad de entradas.

• 4️⃣ Seleccionar Butacas: El usuario elige las butacas entre las disponibles. Esto lo gestiona ButacaDAO.

• 5️⃣ Crear Reserva: Se crea la reserva y se asignan las butacas elegidas. Esto lo realiza ReservaDAO.

• 6️⃣ Seleccionar Combos: Se muestran los combos disponibles (snacks y bebidas). El usuario puede agregar los que desee mediante CandyDAO.

• 7️⃣ Mostrar Resumen Final: Se presenta un resumen con todos los datos: cliente, película, sala, butacas, combos seleccionados y el total a pagar.

Capybara Films está compuesto por distintos módulos y componentes clave que, en conjunto, permiten gestionar todo el proceso de reserva en un cine desde la consola. Estos elementos son las piezas fundamentales del código: clases, entidades y servicios que colaboran para cumplir su rol dentro de la aplicación.

El sistema cubre desde el registro de clientes hasta la generación del ticket final, incluyendo funciones opcionales como la compra de combos. Cada acción está validada y respaldada por acceso a la base de datos con transacciones seguras.

La siguiente tabla ofrece una descripción clara de las funcionalidades que cada componente facilita, las clases o entidades principales involucradas y su ubicación dentro del proyecto.

Además del flujo general y los componentes que vimos antes, el sistema aplica una serie de reglas de negocio y validaciones en cada paso del proceso, para asegurar que la información sea coherente y que la experiencia del usuario sea fluida.

Estas reglas están implementadas a lo largo de las diferentes capas del sistema: desde la validación de entradas del usuario, hasta restricciones internas para garantizar reservas correctas, películas válidas y butacas disponibles.

A continuación se muestra un resumen de las validaciones clave en cada paso del flujo:

Capybara Films se basa en Python 3.x y un conjunto de tecnologías y patrones clave para su operación. Estos elementos aseguran la eficiencia y robustez del sistema, desde la conexión a la base de datos hasta la gestión de fechas y la interacción con el sistema operativo.
El siguiente diagrama ilustra los componentes tecnológicos fundamentales:

graph TD
    %% Nodo Central
    A[**Python 3.x**<br>Entorno de Ejecución Principal]

    %% Patrones de Arquitectura
    subgraph Patrones de Arquitectura
        B[**Patrón DAO**<br>Acceso a Datos]
        C[**Arquitectura por Capas**<br>Separación de Responsabilidades]
        D[**Modelo de Dominio**<br>Entidades del Negocio]
    end

    %% Librerías de Python
    subgraph Librerías de Python
        E[**psycopg2**<br>PostgreSQL Driver]
        F[**datetime**<br>Manejo de Fechas/Horas]
        G[**os**<br>Operaciones de Consola]
    end

    %% Base de Datos
    H[**PostgreSQL**<br>Motor de Base de Datos]

    %% Conexiones
    A --> B
    A --> C
    A --> D
    A --> E
    A --> F
    A --> G

    E --> H

• Python 3.x: Lenguaje principal de desarrollo, conocido por su simplicidad y potencia.

• Patrones de Arquitectura:

  • DAO (Data Access Object): Para separar el acceso a la base de datos del resto de la lógica. Esto mejora la modularidad, facilita el cambio de base de datos en el futuro y simplifica las pruebas.

  • Arquitectura en capas: Divide el sistema en niveles bien definidos (presentación, servicios, acceso a datos, persistencia), lo que mejora la organización y mantenimiento del código.

  • Modelo de dominio: Representación clara de entidades como Cliente, Película, Reserva, entre otras.

• Librerías de Python:

  • psycopg2: Driver oficial para conectarse a bases de datos PostgreSQL desde Python.

  • datetime: Facilita la gestión de fechas y horarios, útil para funciones como horarios de películas o generación de tickets.

  • os: Módulo estándar de Python que provee una interfaz para interactuar con el sistema operativo. Se utiliza para operaciones como limpiar la consola o gestionar rutas de archivos cuando sea necesario.

• Base de datos:

  • PostgreSQL: Motor de base de datos relacional que almacena toda la información del sistema.

Este sistema fue diseñado con mecanismos de manejo de errores que aseguran que el sistema funcione de manera confiable incluso ante situaciones inesperadas. Estos mecanismos permiten evitar caídas, mantener la integridad de la base de datos y brindar una buena experiencia al usuario.

• Captura de excepciones: Se utilizan bloques try-except para detectar y manejar errores en operaciones críticas, evitando que el programa se detenga de forma abrupta.

• Mensajes claros para el usuario: Cuando ocurre un error, se informa lo sucedido con mensajes explicativos que ayudan al usuario a entender el problema sin mostrar detalles técnicos.

• Rollback en transacciones: Si ocurre un fallo durante el proceso de reserva (por ejemplo, si no se puede asignar una butaca), el sistema revierte los cambios realizados para mantener la base de datos en un estado coherente.

• Validación de entradas: Antes de realizar cualquier acción, los datos ingresados por el usuario son validados (por ejemplo, DNI, campos vacíos o formatos incorrectos), reduciendo la posibilidad de errores durante la ejecución.

• Limpieza de recursos: El sistema se asegura de cerrar correctamente conexiones con la base de datos y liberar recursos, incluso si ocurre una excepción.

• Degradación controlada: Ante errores que no son críticos, el sistema puede continuar con otras operaciones o permitir que el usuario intente una acción alternativa, sin forzar el cierre de la aplicación.