Skip to content

RGiskard7/gestion-guardias

BranchesTags

Repository files navigation

gestion-guaridas

Aplicación para la gestión de Guardias de un instituto

Sistema de gestión de guardias para institutos educativos desarrollado con Next.js, TypeScript y Bootstrap. Esta aplicación permite gestionar las ausencias del profesorado, la asignación de guardias y su monitorización diaria.

📑 Tabla de Contenidos

📚 Documentación del proyecto

Para facilitar el uso y comprensión del sistema, se proporciona la siguiente documentación:

Los diagramas de flujo y estados incluyen representaciones detalladas de:

  • Ciclos de vida completos de ausencias y guardias
  • Procesos de anulación con manejo de ausencias asociadas
  • Flujo de firma de guardias con tareas
  • Relaciones entre entidades y sus transiciones de estado
  • Sistema de pestañas para la gestión integral de guardias por parte de los profesores

Todo lo referido a la documentación del proyecto se encuentra en el directorio /doc

📋 Descripción General

El sistema contempla dos tipos de usuarios:

Administrador

  • Gestión completa de usuarios (profesores)
  • Asignación de horarios de guardia
  • Gestión de espacios y ubicaciones
  • Control y supervisión de guardias y ausencias
  • Visualización de estadísticas

Profesor

  • Registro de ausencias
  • Visualización unificada de diferentes tipos de guardias (pendientes, generadas, por firmar)
  • Asignación a guardias disponibles
  • Firma de guardias realizadas
  • Gestión de tareas para los alumnos durante su ausencia
  • Visualización de su horario semanal de guardias

⭐ Funcionalidades Principales

Autenticación

  • Acceso mediante correo electrónico y contraseña
  • Gestión de sesiones mediante Supabase Auth
  • Protección de rutas según roles de usuario
  • Redirección a la pantalla de login cuando se requiere autenticación

Gestión de Usuarios

  • Crear, editar y desactivar usuarios de tipo "profesor"
  • Control de acceso basado en roles (administrador/profesor)
  • Validación de emails únicos al crear nuevos usuarios
  • Gestión de la herencia de horarios a nivel de aplicación entre usuarios

Gestión de Horarios

  • Asignación de tramos de guardia a profesores
  • Gestión de disponibilidad por día y hora
  • Vista semanal de horarios para profesores
  • Vista en formato calendario para mejor visualización
  • Prevención de horarios duplicados para un mismo profesor

Gestión de Espacios

  • Registro y gestión de aulas, patios y otras áreas
  • Asignación de espacios para guardias

Gestión de Guardias

  • Sistema de asignación y firma de guardias
  • Control de restricciones (1 guardia por tramo horario)
  • Límite de 6 guardias por semana por profesor
  • Anulación de guardias con actualización automática de estado
  • Soporte para diferentes tipos de guardia (Aula, Patio, Recreo)
  • Preservación de historial mediante actualización de observaciones en anulaciones
  • Al anular una guardia con ausencia asociada, la ausencia vuelve a estado "Pendiente"
  • Verificación automática de disponibilidad de profesores basada en horario y guardias asignadas
  • Creación de guardias por lotes para múltiples fechas y tramos horarios

Gestión de Ausencias

  • Registro de ausencias por parte de profesores
  • Aprobación o rechazo de ausencias por parte de administradores
  • Creación automática de guardias a partir de ausencias aceptadas
  • Opción "Todo el día" para seleccionar todos los tramos horarios al registrar ausencias
  • Anulación de ausencias con actualización automática de guardias asociadas
  • Trazabilidad completa mediante observaciones con información de cambios de estado
  • Ciclo completo con estados: Pendiente → Aceptada → Pendiente (si se anula la guardia)

Mis Guardias (Profesores)

  • Interfaz unificada con sistema de pestañas para la gestión integral de guardias:
    • Pendientes: Guardias disponibles para asignar, filtradas por horario compatible del profesor
    • Generadas: Guardias creadas a partir de ausencias del profesor
    • Por firmar: Guardias asignadas al profesor que debe cubrir y firmar
  • Navegación mediante parámetros URL que permiten mantener la pestaña activa entre recargas
  • Estado de cada guardia claramente visible con un sistema de etiquetas codificadas por color
  • Acciones contextuales según el tipo de guardia y su estado actual

Sala de Guardias

  • Visualización en tiempo real del estado de las guardias
  • Filtrado por estado (Pendientes, Asignadas, Firmadas)
  • Vista optimizada para pantallas grandes en salas de profesores

Modo Oscuro

  • Interfaz adaptable con modo claro y oscuro
  • Persistencia de la preferencia del usuario
  • Detección automática de preferencias del sistema
  • Compatibilidad mejorada para tablas y componentes en modo oscuro

🗂️ Estructura del proyecto

.                               # Estructura principal del proyecto
├── .gitignore                  # Archivos y directorios ignorados por git
├── README.md                   # Documentación principal del proyecto
├── CHANGELOG.md                # Registro de cambios del proyecto
├── app                         # Directorio principal de Next.js App Router
│   ├── admin                   # Área de administración
│   │   ├── ausencias           # Gestión completa de ausencias
│   │   │   └── page.tsx        # Página de gestión de ausencias
│   │   ├── estadisticas        # Visualización de datos y métricas
│   │   │   └── page.tsx        # Página de estadísticas
│   │   ├── guardias            # Gestión de guardias (vista admin)
│   │   │   └── page.tsx        # Página de gestión de guardias
│   │   ├── horarios            # Configuración de horarios
│   │   │   └── page.tsx        # Página de gestión de horarios
│   │   ├── layout.tsx          # Layout para el área de administración
│   │   ├── lugares             # Gestión de espacios y ubicaciones
│   │   │   └── page.tsx        # Página de gestión de lugares
│   │   ├── page.tsx            # Dashboard principal de admin
│   │   └── users               # Gestión de usuarios
│   │       └── page.tsx        # Página de gestión de usuarios
│   ├── guardia                 # Gestión de guardias específicas
│   │   └── page.tsx            # Página de detalles de guardia
│   ├── layout.tsx              # Layout principal que envuelve toda la app
│   ├── login                   # Autenticación de usuarios
│   │   └── page.tsx            # Página de inicio de sesión
│   ├── metadata.ts             # Configuración de metadatos de la app
│   ├── page.tsx                # Página principal/inicio
│   ├── profesor                # Área de profesores
│   │   ├── ausencias           # Gestión de ausencias del profesor
│   │   │   └── page.tsx        # Página de registro de ausencias
│   │   ├── mis-guardias        # Vista unificada con pestañas
│   │   │   └── page.tsx        # Gestión integral de guardias
│   │   ├── horario             # Visualización del horario semanal
│   │   │   └── page.tsx        # Página de horario del profesor
│   │   ├── layout.tsx          # Layout para el área de profesores
│   │   └── page.tsx            # Dashboard del profesor
│   └── sala-guardias           # Vista general de guardias activas
│       └── page.tsx            # Página de sala de guardias
├── components                  # Componentes reutilizables
│   ├── common                  # Componentes comunes (navbar, sidebar, etc.)
│   │   ├── Navbar.tsx          # Barra de navegación
│   │   └── Sidebar.tsx         # Menú lateral
│   └── ui                      # Componentes de interfaz de usuario
│       └── ...                 # Otros componentes UI
├── doc                         # Documentación adicional
│   ├── DIAGRAMA-ER.md          # Diagrama entidad-relación
│   ├── DIAGRAMAS-ESTADOS.md    # Diagramas de estados
│   ├── DIAGRAMAS-FLUJO.md      # Diagramas de flujo en formato Mermaid
│   ├── MANUAL-USUARIO.md       # Manual de usuario detallado
│   ├── MANUAL-PROGRAMADOR.md   # Manual técnico
│   ├── SUPABASE.md             # Documentación de Supabase
│   ├── images                  # Imágenes para la documentación
│   └── ...                     # Otra documentación
├── hooks                       # Custom hooks de React
├── lib                         # Utilidades y configuraciones
│   ├── authService.ts          # Servicio de autenticación
│   ├── ausenciasService.ts     # Servicio de ausencias
│   ├── db-config.ts            # Configuración de la base de datos
│   ├── guardiasService.ts      # Servicio de guardias
│   ├── horariosService.ts      # Servicio de horarios
│   ├── lugaresService.ts       # Servicio de lugares
│   ├── supabaseClient.ts       # Cliente de Supabase
│   ├── tareasGuardiaService.ts # Servicio de tareas de guardia
│   └── usuariosService.ts      # Servicio de usuarios
├── middleware.ts               # Middleware de Next.js para autenticación y rutas
├── scripts                     # Scripts de utilidad
│   └── create-tables.sql       # Script SQL para crear tablas en Supabase
└── src                         # Código fuente adicional
    ├── App.css                 # Estilos principales de la aplicación
    └── contexts                # Contextos de React para estado global
        ├── AuthContext.tsx     # Contexto de autenticación
        ├── GuardiasContext.tsx # Contexto de gestión de guardias
        └── ThemeContext.tsx    # Contexto para gestión del tema

📸 Capturas de Pantalla

Captura 1

Captura 2

Captura 3

Captura 4

Captura 5

Captura 6

Captura 7

Captura 8

Captura 9

Captura 10

Captura 11

Captura 12

📽️ Video Demo

Puedes ver una demostración del funcionamiento del sistema en este enlace.

�� Requisitos Previos

  • Node.js (versión 18 o superior)
  • npm (viene incluido con Node.js)
  • Cuenta en Supabase para la base de datos

⚙️ Instalación

  1. Clona el repositorio:
git clone https://github.com/RGiskard7/gestion-guardias.git
cd gestion-guardias
  1. Instala las dependencias:
npm install --legacy-peer-deps

Nota: Utilizamos --legacy-peer-deps debido a algunas incompatibilidades entre las dependencias de date-fns y react-day-picker. Este flag permite que la instalación se complete correctamente.

  1. Configura las variables de entorno:

    • Copia el archivo example.env.local a .env.local:
    cp example.env.local .env.local
    • Edita el archivo .env.local y reemplaza los valores de ejemplo con tus credenciales de Supabase

  2. Configura Supabase:

    • Sigue las instrucciones en SUPABASE.md
    • Asegúrate de que las variables en tu archivo .env.local coincidan con las credenciales de tu proyecto en Supabase

🚀 Ejecución del Proyecto

Para iniciar el servidor de desarrollo:

npm run dev

El servidor se iniciará en http://localhost:3000. Puedes acceder a la aplicación abriendo esta URL en tu navegador.

Para probar la aplicación, consulta las instrucciones detalladas en INSTRUCCIONES-PRUEBA.md.

💻 Scripts Disponibles

  • npm run dev - Inicia el servidor de desarrollo
  • npm run build - Crea una versión optimizada para producción
  • npm start - Inicia el servidor en modo producción
  • npm run lint - Ejecuta el linter para verificar el código
  • npm run check-db - Verifica la estructura de la base de datos

🛠️ Tecnologías Principales

  • Next.js 15.1.0
  • React 19
  • TypeScript
  • Bootstrap 5.3.2
  • Supabase (Backend y Base de datos)
  • date-fns
  • react-day-picker

📊 Estado Actual de los Datos

La aplicación utiliza Supabase como backend para proporcionar:

  • Persistencia de datos en una base de datos PostgreSQL
  • Autenticación y autorización basada en roles
  • API para comunicación cliente-servidor
  • Manejo profesional de IDs y transacciones

Para más detalles sobre la implementación con Supabase, consulta SUPABASE.md.

🗄️ Estructura de la Base de Datos

Para una representación visual de la estructura de la base de datos y las relaciones entre tablas, consulta el Diagrama Entidad-Relación.

Tablas Principales

  1. Usuarios

    • id (PK)
    • nombre
    • apellido
    • email
    • password
    • rol
    • activo

  2. Horarios

    • id (PK)
    • profesor_id (FK)
    • dia_semana
    • tramo_horario

  3. Lugares

    • id (PK)
    • codigo
    • descripcion
    • tipo_lugar

  4. Ausencias

    • id (PK)
    • profesor_id (FK) - Profesor que se ausenta
    • fecha - Día de la ausencia
    • tramo_horario - Período específico de ausencia
    • estado - Pendiente/Aceptada/Rechazada
    • observaciones - Incluye motivos, comentarios y registros de cambios de estado

  5. Guardias

    • id (PK)
    • fecha - Día de la guardia
    • tramo_horario - Período específico de la guardia
    • tipo_guardia - Aula/Patio/Recreo
    • firmada - Indica si ha sido completada (true/false)
    • estado - Pendiente/Asignada/Firmada/Anulada
    • observaciones - Incluye información de la guardia y registros de cambios
    • lugar_id (FK) - Ubicación donde se realiza la guardia
    • profesor_cubridor_id (FK) - Profesor asignado para cubrir la guardia
    • ausencia_id (FK) - Ausencia asociada (si proviene de una)

  6. Tareas_guardia

    • id (PK)
    • guardia_id (FK) - Guardia a la que pertenece la tarea
    • descripcion - Descripción de las tareas realizadas durante la guardia

📓 Bitácora de Desarrollo

La bitácora de desarrollo se mantiene en el archivo CHANGELOG.md. Este documento registra todos los cambios, mejoras y correcciones realizadas en el proyecto de forma cronológica.

Formato de Entradas

Cada entrada en la bitácora debe seguir el siguiente formato:

## [YYYY-MM-DD] - Título descriptivo de los cambios

### Autor(es)
- Nombre del desarrollador

### Cambios realizados
- Descripción detallada del cambio 1
- Descripción detallada del cambio 2

### Archivos modificados
- `ruta/al/archivo1.tsx`: Descripción breve de la modificación
- `ruta/al/archivo2.ts`: Descripción breve de la modificación

### Problemas resueltos
- Descripción del problema 1 que se ha solucionado
- Descripción del problema 2 que se ha solucionado

### Notas adicionales
- Cualquier información relevante adicional (si aplica)

Para añadir una nueva entrada, copia esta plantilla al principio del archivo CHANGELOG.md y completa la información correspondiente.

📖 Bibliografía y Referencias

Documentación Oficial

Arquitectura y Patrones

Seguridad

Rendimiento y Optimización

Diseño UI/UX

Tutoriales y Guías

Herramientas de Desarrollo

Desarrollado por Edu Díaz a.k.a RGiskard7 ❤️

About

Sistema de gestión de guardias para centros educativos. Permite administrar ausencias del profesorado, asignación de guardias y su monitorización en tiempo real. Desarrollado con Next.js, TypeScript y Bootstrap.

Topics

bootstrap typescript educacion next-js profesorado supabase gestion-guardias sistema-educativo ausencias administracion-escolar

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages