🚗 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)

# Clonar el repositorio
git clone <url-del-repositorio>
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

   # Si tienes git instalado
   git clone <url-del-repositorio>
   cd balotario-licencia-a1
   

2. Configura las variables de entorno

   # 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

   pip install -r requirements.txt
   

4. Ejecuta la aplicación

   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

# 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 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:

### [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 <style>.

Agregar funcionalidades

Modifica app.py para agregar nuevas rutas o funcionalidades.

🐛 Solución de Problemas

La aplicación no inicia

• Verifica que Python esté instalado: python --version
• Instala las dependencias: pip install -r requirements.txt
• Verifica que el puerto 5000 esté libre

Las preguntas no se cargan

• Verifica que el archivo balotario_clase_a_cat_I.md esté presente
• Revisa la consola para errores de parsing

Problemas con imágenes

• Las imágenes se cargan desde URLs externas
• Verifica tu conexión a internet

📝 Licencia

Este proyecto está licenciado bajo la GNU General Public License v3.0 (GPL-3.0).

¿Qué significa esto?

• ✅ Libertad de uso: Puedes usar este software para cualquier propósito
• ✅ Libertad de estudio: Puedes estudiar cómo funciona y modificarlo
• ✅ Libertad de distribución: Puedes redistribuir copias para ayudar a otros
• ✅ Libertad de mejora: Puedes mejorar el programa y publicar las mejoras

Condiciones importantes

• 📋 Código abierto: Si distribuyes versiones modificadas, debes mantener el código fuente disponible
• 📋 Misma licencia: Las obras derivadas deben usar la misma licencia GPL-3.0
• 📋 Atribución: Debes mantener los avisos de copyright y licencia originales

Contenido educativo

El contenido del balotario está basado en las preguntas oficiales del MTC (Ministerio de Transportes y Comunicaciones) del Perú y es de dominio público para fines educativos.

Para más detalles, consulta el archivo LICENSE en este repositorio.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Puedes:

• Reportar bugs
• Sugerir nuevas funcionalidades
• Mejorar la documentación
• Optimizar el código

📞 Soporte

Si tienes problemas o preguntas:

1. Revisa este README
2. Verifica los logs de la aplicación
3. Busca en los issues del repositorio

---

¡Buena suerte en tu examen de manejo! 🚗💨