🎯 Misión Template - Plantilla para Talleres Educativos Interactivos

Una plantilla lista para usar que te permite crear aplicaciones web interactivas para talleres educativos con sistema de misiones, equipos, puntuación y seguimiento en tiempo real.

✨ ¿Qué incluye esta plantilla?

🏗️ Estructura Completa

• Backend: Node.js + Fastify + Socket.IO + SQLite
• Frontend: React + Vite + Styled Components
• Base de Datos: SQLite con sistema de migraciones
• Validación: Zod para esquemas de datos
• Testing: Jest configurado para backend y frontend
• Docker: Configuración lista para despliegue

🎮 Funcionalidades Base

• ✅ Sistema de sesiones con códigos únicos
• ✅ Gestión de equipos con nombres personalizados
• ✅ Sistema de misiones progresivas (3 misiones + fase final)
• ✅ Sistema de pistas con penalización configurable
• ✅ Temporizadores configurables por sesión
• ✅ Tablero de puntuación en tiempo real
• ✅ Vista para profesores con control total
• ✅ Vista para equipos con interfaz intuitiva
• ✅ Exportación de resultados a CSV
• ✅ Websockets para actualizaciones en tiempo real
• ✅ Rate limiting y medidas de seguridad

🚀 Inicio Rápido

Requisitos

• Node.js 18+ y npm
• (Opcional) Docker y Docker Compose

Instalación

# 1. Clonar/copiar este proyecto
cd mision-template

# 2. Instalar dependencias de todo el proyecto
npm run install:all

# 3. Configurar el backend
cd api
cp env.example .env
npm run migrate

# 4. Iniciar en modo desarrollo
cd ..
npm run dev

El frontend estará en http://localhost:5173 y el backend en http://localhost:3000

Con Docker

docker-compose up --build

📝 Personaliza tu Taller

1. Define tus Misiones

Edita api/src/mission-configs.js:

// 1. Define las plantillas de tus misiones
export const missionTemplates = {
  m1: {
    name: 'Misión 1: Tu título aquí',
    description: 'Descripción de la misión. Usa {placeholders} para valores dinámicos',
    hints: [
      '🔍 Pista 1: Primera pista con {placeholder}',
      '📍 Pista 2: Segunda pista',
      '🎯 Pista 3: Tercera pista con la solución'
    ]
  },
  // ... más misiones
};

// 2. Define los valores concretos para cada misión
export const equationSets = {
  basic: [
    {
      key: 'm1',
      // Agrega aquí todos los valores que necesites
      // Estos reemplazarán los {placeholders} en las plantillas
    },
    // ... más configuraciones
  ]
};

2. Personaliza la Validación

Edita api/src/validators.js para definir cómo se validan las respuestas de cada misión.

3. Ajusta la Interfaz

Los componentes principales están en:

• web/src/components/team/ - Vista de equipos
• web/src/components/teacher/ - Vista de profesor
• web/src/components/common/ - Componentes compartidos

4. Configura el Sistema de Puntos

En api/src/index.js encontrarás la configuración de:

• Puntos por misión completada
• Penalización por pistas
• Tiempo límite por misión
• Bonificaciones

📁 Estructura del Proyecto

mision-template/
├── api/                    # Backend
│   ├── src/
│   │   ├── index.js       # Servidor principal
│   │   ├── mission-configs.js  # ⭐ PERSONALIZA TUS MISIONES AQUÍ
│   │   ├── validators.js  # ⭐ VALIDA RESPUESTAS AQUÍ
│   │   ├── tasks.js       # Lógica de misiones
│   │   ├── store.js       # Estado en memoria
│   │   ├── config/        # Configuraciones de seguridad
│   │   ├── database/      # Conexión a BD
│   │   ├── middleware/    # Middleware de seguridad
│   │   ├── migrations/    # Esquema de base de datos
│   │   └── routes/        # Endpoints API
│   └── package.json
├── web/                   # Frontend
│   ├── src/
│   │   ├── App.jsx       # Componente principal
│   │   ├── components/
│   │   │   ├── common/   # Componentes reutilizables
│   │   │   ├── teacher/  # Vista del profesor
│   │   │   └── team/     # ⭐ Vista de equipos (PERSONALIZA)
│   │   ├── hooks/        # Hooks personalizados
│   │   └── state/        # Estado global
│   └── package.json
├── docs/                  # Documentación
├── docker-compose.yml     # Configuración Docker
└── package.json          # Scripts del proyecto

🔧 Variables de Entorno

Crea un archivo .env en la carpeta api/:

# Servidor
PORT=3000
NODE_ENV=development

# Base de datos
DB_PATH=./data/database.db

# Seguridad
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
RATE_LIMIT_MAX=100
RATE_LIMIT_TIMEWINDOW=60000

# Websockets
WS_CORS_ORIGIN=http://localhost:5173

🎯 Flujo del Taller

1. Profesor crea sesión → Genera código único
2. Equipos se unen → Ingresan código y nombre de equipo
3. Profesor configura tiempos → Establece duración de cada misión
4. Inicia el taller → Misión 1 se activa para todos
5. Equipos resuelven misiones → Pueden pedir pistas (con penalización)
6. Validación automática → Sistema valida respuestas
7. Progresión → Al completar una misión, se desbloquea la siguiente
8. Fase final → Después de las 3 misiones
9. Exportación → Profesor descarga resultados en CSV

🧪 Testing

# Backend
cd api
npm test

# Frontend
cd web
npm test

# Con cobertura
npm run test:coverage

📦 Despliegue

Render.com

El archivo render.yaml está listo para desplegar en Render.

Docker

docker-compose up -d

🛠️ Tecnologías

• Backend: Fastify, Socket.IO, SQLite, Zod, Math.js
• Frontend: React, Vite, Styled Components
• Testing: Jest, React Testing Library
• Deploy: Docker, Render

📚 Documentación Adicional

• docs/API.md - Documentación completa de la API
• docs/DEVELOPMENT.md - Guía de desarrollo

🤝 Contribuir

Esta es una plantilla base. Siéntete libre de:

• Agregar más misiones
• Personalizar la interfaz
• Mejorar las validaciones
• Agregar nuevas funcionalidades

📄 Licencia

MIT - Usa esta plantilla libremente para tus proyectos educativos.

---

🎓 Perfecto para: Talleres de matemáticas, física, química, programación, y cualquier disciplina que requiera resolución de problemas interactivos con equipos.