driving-academy/README.md

# 🚗 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 <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**
   ```bash
   # Si tienes git instalado
   git clone <url-del-repositorio>
   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 `<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](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! 🚗💨**