# 🚗 Balotario Licencia Clase A - Categoría I Una aplicación web interactiva desarrollada con Flask para estudiar las preguntas del balotario oficial de la licencia de conducir Clase A - Categoría I del Perú. ## ✨ Características - **📚 Modo Estudio**: Revisa todas las preguntas con sus respuestas correctas - **🏋️ Modo Práctica**: Practica con preguntas aleatorias y retroalimentación inmediata - **📝 Examen Simulado**: Simula el examen real con tiempo limitado - **📊 Estadísticas**: Seguimiento de tu progreso y precisión - **🖼️ Imágenes**: Incluye todas las señales de tránsito oficiales - **📱 Responsive**: Funciona perfectamente en móviles y tablets - **🎨 Interfaz Moderna**: Diseño atractivo y fácil de usar ## 🚀 Instalación y Configuración ### 🐳 Opción 1: Docker (Recomendado) ```bash # Clonar el repositorio git clone cd balotario-licencia-a1 # Opción A: Docker Compose (más fácil) docker-compose up -d # Opción B: Docker simple docker build -t balotario . docker run -p 5000:5000 balotario # Opción C: Script de utilidades ./scripts/docker.sh compose-up ``` ### 🐍 Opción 2: Instalación Local #### Prerrequisitos - Python 3.7 o superior - pip (gestor de paquetes de Python) #### Pasos de instalación 1. **Clona o descarga el proyecto** ```bash # Si tienes git instalado git clone cd balotario-licencia-a1 ``` 2. **Configura las variables de entorno** ```bash # Linux/Mac ./scripts/env-setup.sh dev # Windows scripts\env-setup.bat dev # O manualmente cp .env.sample .env # Edita .env con tus valores ``` 3. **Instala las dependencias** ```bash pip install -r requirements.txt ``` 4. **Ejecuta la aplicación** ```bash python run.py ``` 5. **Abre tu navegador** - Ve a: `http://localhost:5000` - ¡Listo para estudiar! 🎉 ### 🌐 Acceso - **Docker**: `http://localhost:5000` (o `http://localhost` con Nginx) - **Local**: `http://localhost:5000` ## ⚙️ Configuración de Variables de Entorno ### 🔧 Configuración Rápida ```bash # Desarrollo local ./scripts/env-setup.sh dev # Producción ./scripts/env-setup.sh prod # Docker ./scripts/env-setup.sh docker ``` ### 📋 Variables Principales | Variable | Descripción | Por Defecto | |----------|-------------|-------------| | `SECRET_KEY` | Clave secreta de Flask | `balotario_secret_key_2024_super_secure` | | `FLASK_ENV` | Entorno de ejecución | `development` | | `FLASK_DEBUG` | Modo debug | `true` | | `HOST` | Dirección del servidor | `127.0.0.1` | | `PORT` | Puerto del servidor | `5000` | ### 📚 Documentación Completa Ver [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) para configuración avanzada. ## 📖 Cómo usar la aplicación ### 🏠 Página Principal - Resumen de estadísticas - Acceso rápido a todos los modos - Información del balotario ### 📚 Modo Estudio - Navega por todas las preguntas secuencialmente - Filtra por rango de preguntas - Muestra/oculta respuestas correctas - Navegación con teclado (flechas y espacio) ### 🏋️ Modo Práctica - Selecciona el número de preguntas (10, 20, 30, 50) - Preguntas aleatorias - Retroalimentación inmediata - Estadísticas de sesión ### 📝 Examen Simulado - Configura número de preguntas y tiempo límite - Cronómetro en tiempo real - Navegador de preguntas - Calificación final con porcentaje de aprobación ## 🛠️ Estructura del Proyecto ``` balotario-licencia-a1/ ├── app.py # Aplicación Flask principal ├── run_app.py # Script de inicio mejorado ├── config.py # Configuración modular ├── requirements.txt # Dependencias Python ├── data/ # Datos y contenido │ ├── balotario_clase_a_cat_I.md # 200 preguntas oficiales │ ├── README.md # Documentación del contenido │ └── backup/ # Respaldos del contenido ├── templates/ # Templates HTML │ ├── base.html # Template base │ ├── index.html # Página principal │ ├── study.html # Modo estudio │ ├── practice.html # Modo práctica │ └── exam.html # Examen simulado ├── static/ # Archivos estáticos │ ├── css/ │ │ └── custom.css # Estilos personalizados │ └── js/ │ └── app.js # JavaScript principal ├── test/ # Tests y pruebas │ ├── README.md # Documentación de tests │ ├── test_parser.py # Tests del parser │ ├── test_sounds.html # Tests de sonidos │ └── ... # Otros tests ├── scripts/ # Scripts de utilidades │ └── dev.py # Herramientas de desarrollo ├── CHANGELOG.md # Registro de cambios ├── INSTALL.md # Guía de instalación └── README.md # Esta documentación ``` ## 🎯 Funcionalidades Técnicas ### Backend (Flask) - **API RESTful** para obtener preguntas - **Sesiones** para estadísticas persistentes - **Parser inteligente** del markdown con regex - **Filtros dinámicos** por rango y modo ### Frontend - **Bootstrap 5** para diseño responsive - **jQuery** para interactividad - **Font Awesome** para iconos - **Animaciones CSS** para mejor UX - **LocalStorage** para persistencia del lado cliente ### Características Especiales - **Navegación por teclado** en modo estudio - **Cronómetro visual** en examen simulado - **Navegador de preguntas** con estado visual - **Estadísticas en tiempo real** - **Confirmación antes de finalizar examen** ## 📊 Datos del Balotario - **200 preguntas** oficiales - **Respuestas correctas** marcadas con ✅ - **Imágenes de señales** de tránsito incluidas - **Categorías**: Reglamentarias, preventivas, informativas - **Temas**: Normas de tránsito, señalización, seguridad vial ## 🔧 Personalización ### Modificar preguntas Edita el archivo `balotario_clase_a_cat_I.md` siguiendo el formato: ```markdown ### [NÚMERO] [PREGUNTA] a) [OPCIÓN A] b) [OPCIÓN B] c) [OPCIÓN C] ✅ d) [OPCIÓN CORRECTA] ``` ### Cambiar estilos Los estilos CSS están en `templates/base.html` dentro de la etiqueta `