DOCUMENTACION TECNICA - SISTEMA PARTE DIARIO DOCENTE ===================================================== SECCION 1: PORTADA ------------------ Nombre del Sistema: Parte Diario Docente Descripcion: Sistema web para la gestion y registro diario de actividades academicas docentes Fecha de Creacion: Julio 2026 Institucion: Institucion Educativa Superior (Generica) Version del Documento: 1.0 Estado: Documento de referencia tecnica SECCION 2: DESCRIPCION GENERAL DEL SISTEMA ------------------------------------------- El sistema "Parte Diario Docente" es una plataforma web disenada para centralizar y automatizar el proceso de registro, revision y seguimiento de las actividades academicas diarias que realizan los docentes en una institucion educativa. Su proposito fundamental es reemplazar los reportes en papel o planillas manuales por un sistema digital que permita el monitoreo en tiempo real del cumplimiento academico. El sistema opera bajo un modelo de tres roles principales. En primer lugar, los docentes pueden registrar diariamente las clases que imparten, incluyendo el tema del silabo que trabajaron, las actividades realizadas en clase, las tareas dejadas a los estudiantes y cualquier observacion relevante. En segundo lugar, los coordinadores de programa revisan y aprueban o rechazan los registros de sesion de los docentes que pertenecen a su programa academico, pudiendo agregar comentarios cuando identifican observaciones. En tercer lugar, los administradores tienen acceso total al sistema, pudiendo gestionar usuarios, periodos academicos, programas, configuraciones del sistema y exportar reportes globales. Una caracteristica importante del sistema es su capacidad para determinar automaticamente si un registro fue enviado dentro del plazo permitido o fuera de el. El sistema evalua la hora de envio del registro respecto a la hora de finalizacion de la clase, y usando un valor de tolerancia configurable, clasifica cada registro como "en tiempo" o "fuera de plazo". Esta clasificacion permite generar estadisticas de cumplimiento y facilita la labor de supervision de los coordinadores. El sistema tambien genera estadisticas y paneles de control adaptados a cada rol. Los administradores ven metricas globales de toda la institucion, los coordinadores ven metricas filtradas por su programa academico, y los docentes ven metricas personales de su actividad. Estas metricas incluyen total de docentes activos, cursos registrados, clases del dia, registros completados, registros pendientes y porcentaje de cumplimiento. Finalmente, el sistema ofrece capacidades de exportacion de reportes en multiples formatos: PDF para documentos formales, Excel para analisis de datos y CSV para integracion con otras herramientas. Los reportes pueden filtrarse por docente, curso, periodo academico, rango de fechas y estado de revision. SECCION 3: OBJETIVOS --------------------- Objetivo General: Desarrollar un sistema web que permita el registro, control y seguimiento de las actividades academicas diarias de los docentes de una institucion educativa, optimizando el proceso de reporte y facilitando la toma de decisiones basada en datos oportunos y confiables. Objetivos Especificos: 1. Implementar un modulo de autenticacion seguro que permita a los docentes iniciar sesion mediante su DNI y contrasena, y a los administradores y coordinadores mediante su correo electronico y contrasena, con proteccion contra ataques de fuerza bruta. 2. Disenar un formulario de registro de sesiones diarias que capture toda la informacion academica relevante: tema del silabo, actividades realizadas, tareas asignadas y observaciones del docente. 3. Establecer un mecanismo automatico de clasificacion temporal que determine si un registro fue enviado dentro del plazo o fuera de el, usando una tolerancia configurable desde la base de datos. 4. Desarrollar un modulo de revision y aprobacion que permita a los coordinadores validar la informacion registrada por los docentes de su programa, emitiendo aprobaciones o rechazos con comentarios. 5. Construir paneles de control dinamicos y adaptativos que muestren indicadores clave de rendimiento filtrados por el rol del usuario autenticado. 6. Implementar un sistema de notificaciones que informe a los usuarios sobre eventos relevantes como aprobaciones, rechazos y solicitudes de contrasena. 7. Generar un registro completo de auditoria que capture todas las acciones relevantes realizadas en el sistema, incluyendo accesos, modificaciones y eventos de seguridad. 8. Ofrecer funcionalidad de exportacion de reportes en formatos PDF, Excel y CSV, con filtros por docente, curso, periodo y rango de fechas. 9. Implementar un sistema de solicitudes de cambio de contrasena para docentes, con flujo de aprobacion por parte del administrador. 10. Mantener la integridad referencial de los datos mediante claves foraneas y restricciones unicas en la base de datos. SECCION 4: STACK TECNOLOGICO ----------------------------- El sistema esta construido sobre un conjunto de tecnologias seleccionadas por su idoneidad para el tipo de aplicacion, la disponibilidad de recursos y la experiencia del equipo de desarrollo. Backend - CodeIgniter 4: CodeIgniter 4 fue elegido como framework backend por ser un framework ligero, rapido y de bajo overhead para aplicaciones PHP. A diferencia de frameworks mas pesados como Laravel o Symfony, CodeIgniter 4 ofrece un arranque rapido, una estructura de directorios clara y un rendimiento excepcional. Su enfoque en simplicidad no compromete las funcionalidades necesarias: soporte completo para el patron MVC, sistema de migraciones para base de datos, sistema de routing configurable, y un motor de vistas nativo que permite renderizado eficiente del lado del servidor. CodeIgniter 4 tambien incluye Shield, su libreria oficial de autenticacion y autorizacion, lo que eliminó la necesidad de integrar una libreria externa para seguridad. PHP 8.2 o superior: El sistema requiere PHP version 8.2 o superior para aprovechar las funcionalidades modernas del lenguaje. PHP 8.2 introduce tipos deprecados, atributos de enumeracion y mejoras significativas de rendimiento. El uso de tipos estrictos en los controladores y modelos mejora la fiabilidad del codigo y facilita el mantenimiento. La declaracion de tipos en argumentos de funciones, valores de retorno y propiedades permite detectar errores en tiempo de compilacion en lugar de ejecucion. MySQL 8.0 o superior: MySQL 8.0 fue seleccionado como sistema de gestion de base de datos relacional por su madurez, confiabilidad y soporte completo para las funcionalidades requeridas: claves foraneas, restricciones unicas, campos ENUM, campos SET, valores por defecto con expresiones como CURRENT_TIMESTAMP, y transacciones ACID. El uso de MySQL permite garantizar la integridad referencial de los datos, lo cual es critico en un sistema academico donde la relacion entre docentes, cursos, horarios y registros debe mantenerse consistente. CodeIgniter Shield: Shield es la libreria oficial de autenticacion y autorizacion de CodeIgniter 4. Fue elegida por su integracion nativa con el framework, eliminando la complejidad de configurar un sistema de autenticacion desde cero. Shield proporciona autenticacion basada en sesiones, manejo de grupos (roles), filtros de rutas para proteccion de accesos, registro de identidades de autenticacion, y un sistema extensible de eventos. En este sistema, Shield se configura con tres grupos: admin, coordinador y docente, cada uno con permisos diferenciados. Tailwind CSS: Tailwind CSS es un framework de estilos CSS basado en utilidades que permite construir interfaces de usuario rapidamente sin escribir CSS personalizado extenso. Fue elegido por su enfoque en productividad: en lugar de crear clases CSS semanticas, se aplican clases de utilidad directamente en el HTML. Esto acelera el desarrollo y mantiene la consistencia visual. Tailwind CSS se compila localmente como un archivo CSS estatico optimizado para produccion. HTMX: HTMX es una libreria JavaScript que extiende HTML con atributos que permiten realizar solicitudes AJAX, cargar contenido parcialmente y actualizar secciones de la pagina sin recargas completas. Fue integrada para proporcionar una experiencia de usuario similar a una aplicacion de pagina unica (SPA) sin la complejidad de un framework JavaScript frontend completo. Con HTMX, la navegacion del sidebar carga el contenido nuevo reemplazando solo el area principal, las acciones de formulario envian datos y actualizan respuestas, y las tablas se recargan dinamicamente sin refrescar toda la pagina. Esto reduce significativamente el tiempo de respuesta percibido por el usuario. Chart.js: Chart.js es una libreria JavaScript para la creacion de graficos y visualizaciones de datos. Se utilizo para generar los graficos de barras en el dashboard que muestran la actividad de registros de los ultimos siete dias. Chart.js fue elegido por su facilidad de uso, soporte para multiples tipos de graficos y capacidad de actualizacion dinamica a traves de datos JSON cargados desde la API del servidor. SweetAlert2: SweetAlert2 es una libreria JavaScript que reemplaza las ventanas de alerta nativas del navegador con modales esteticamente agradables y personalizables. Se utiliza para confirmaciones de eliminacion, mensajes de exito, advertencias y formularios emergentes. Su integracion con HTMX permite mostrar alertas despues de completar acciones asincronas. GSAP (GreenSock Animation Platform): GSAP es una libreria profesional de animacion JavaScript. Se utiliza para animaciones sutiles de entrada en las paginas del sistema, proporcionando transiciones fluidas que mejoran la experiencia visual sin sacrificar rendimiento. Las animaciones incluyen efectos de aparicion de tarjetas de KPI, transiciones de contenido y efectos hover en elementos interactivos. DomPDF: DomPDF es una libreria PHP que genera documentos PDF a partir de HTML y CSS. Se utiliza para generar reportes exportables del sistema, incluyendo reportes de registros de sesion, reportes de cumplimiento y reportes de actividad docente. DomPDF permite usar estilos CSS basicos para definir la apariencia de los documentos PDF generados. PhpSpreadsheet: PhpSpreadsheet es una libreria PHP para la lectura y escritura de archivos de hojas de calculo en formatos Excel (XLSX) y CSV. Se utiliza para exportar datos del sistema en formatos compatibles con Microsoft Excel y otras herramientas de hojas de calculo. La libreria permite estilizar las celdas, definir anchos de columna y agregar encabezados formateados. Google Material Symbols: El sistema utiliza la fuente de iconografia Google Material Symbols para representar iconos en la interfaz de usuario. Esta coleccion ofrece miles de iconos consistentes en multiples pesos y estilos, lo que facilita mantener una apariencia visual uniforme en toda la aplicacion sin necesidad de archivos de imagen individuales. Laragon: Laragon es un entorno de desarrollo local para Windows que incluye Apache, MySQL y PHP preconfigurados. Se utilizo como servidor de desarrollo local por su facilidad de uso, capacidad de crear hosts virtuales automaticamente, y proporcionar un entorno de prueba estable que replica las condiciones de un servidor de produccion. SECCION 5: ARQUITECTURA DEL SISTEMA ------------------------------------- El sistema sigue el patron de arquitectura Modelo-Vista-Controlador (MVC), que separa la logica de negocio, la presentacion visual y el flujo de peticiones en componentes independientes y bien definidos. Modelos (Models): Los modelos son clases PHP que encapsulan toda la interaccion con la base de datos y la logica de negocio asociada. Cada modelo representa una tabla de la base de datos y proporciona metodos para consultar, insertar, actualizar y eliminar registros. Los modelos del sistema incluyen RegistroSesionModel para la tabla central de registros diarios, DocenteModel para datos de docentes, CursoModel para cursos academicos, HorarioModel para horarios de clases, AsignacionModel para asignaciones curso-docente-periodo, ProgramaModel para programas academicos, PeriodoAcademicoModel para periodos academicos, FeriadoModel para feriados, FranjaAcademicaModel para franjas horarias, HorarioAcademicoModel para configuracion global de horarios, DisponibilidadModel para disponibilidad docente, ConfigSistemaModel para configuraciones del sistema, AuditoriaModel para registros de auditoria, NotificacionModel para notificaciones, LoginAttemptsModel para intentos de acceso, SolicitudPasswordModel para solicitudes de cambio de contrasena, y AuthModel para operaciones de autenticacion. Vistas (Views): Las vistas son archivos PHP que mezclan logica de presentacion con HTML generado dinamicamente. Utilizan el motor de plantillas nativo de CodeIgniter 4 y estan estilizadas completamente con clases de Tailwind CSS. Las vistas estan organizadas por rol en subdirectorios: vistas para administrador, vistas para coordinador, vistas para docente, y vistas compartidas como el layout principal y componentes comunes. Las vistas renderizan componentes como tarjetas de KPI, tablas de datos, formularios de registro, modales de confirmacion y graficos. Controladores (Controllers): Los controladores actuan como intermediarios entre las peticiones HTTP y los modelos/vistas. Reciben las peticiones del usuario, validan los datos de entrada, invocan los metodos correspondientes de los modelos y retornan las vistas o respuestas JSON apropiadas. Los controladores estan organizados en espacios de nombres por rol: Admin para los controladores de administrador, Coordinador para los de coordinador, y Docente para los de docente. Ademas, existe un controlador de autenticacion para el login de admin/coordinador y un controlador especializado para el login de docentes. Patron de Traits: El sistema implementa un patron de traits para promover la reutilizacion de codigo entre multiples controladores. El trait AuditLogger proporciona un metodo para registrar eventos de auditoria en la base de datos, capturando automaticamente el usuario, la tabla afectada, la accion realizada, una descripcion del cambio, la fecha del evento y la direccion IP del cliente. Este trait es utilizado por praticamente todos los controladores del sistema. El trait DiaHelper proporciona metodos para traducir nombres de dias de la semana del ingles al espanol, lo cual es necesario porque PHP retorna los dias en ingles por defecto mientras que el sistema almacena los dias en espanol. El trait LoginAttemptHandler encapsula la logica de verificacion de bloqueo por intentos fallidos de acceso, el registro de intentos exitosos y fallidos, y la limpieza de intentos previos tras un acceso exitoso. Organizacion por Espacios de Nombre: La organizacion del codigo sigue una estructura jerarquica de espacios de nombre que refleja la estructura de directorios del proyecto. Los controladores de administrador se encuentran en el espacio de nombre App\Controllers\Admin, los de coordinador en App\Controllers\Coordinador, los de docente en App\Controllers\Docente, y los compartidos en App\Controllers directamente. Esta organizacion facilita la navegacion del codigo, permite una proteccion de rutas por rol mas intuitiva, y mantiene separada la logica de cada tipo de usuario. Renderizado Parcial con HTMX: Una caracteristica arquitectonica clave es el soporte para renderizado parcial basado en HTMX. El controlador base del sistema verifica la presencia del encabezado HX-Request en cada peticion. Cuando este encabezado esta presente, significa que la peticion fue originada por HTMX y el sistema retorna unicamente el contenido HTML de la vista solicitada, sin el layout completo. Cuando el encabezado no esta presente, el sistema retorna la vista envuelta dentro del layout completo con sidebar, header y footer. Este patron permite que HTMX cargue contenido dinamicamente en el area principal de la interfaz mientras mantiene el sidebar y el header estaticos, proporcionando una experiencia de navegacion fluida y rapida. SECCION 6: SISTEMA DE AUTENTICACION Y AUTORIZACION ---------------------------------------------------- El sistema implementa un mecanismo de autenticacion dual que se adapta a los dos tipos de usuarios principales. Los administradores y coordinadores inician sesion utilizando su correo electronico y contrasena, mientras que los docentes inician sesion utilizando su numero de DNI (Documento Nacional de Identidad) y contrasena. Esta diferenciacion responde a una decision de diseno: los docentes pueden no tener correo electronico institucional asignado, por lo que usar el DNI como identificador unico facilita su acceso al sistema. Tres Roles del Sistema: El sistema define tres roles claramente diferenciados. El rol de administrador tiene acceso completo a todas las funcionalidades del sistema, incluyendo gestion de usuarios, configuracion del sistema, periodos academicos, programas, franjas academicas, feriados, horario academico global, registros de sesion de todos los docentes, auditoria, solicitudes de contrasena y exportacion de reportes globales. El rol de coordinador tiene acceso restringido a las funcionalidades relacionadas con su programa academico especifico. Puede gestionar cursos, horarios, asignaciones, disponibilidad docente, revisar y aprobar o rechazar registros de sesion de los docentes de su programa, ver estadisticas filtradas por programa, exportar reportes de su programa y ver un horario semanal consolidado. El rol de docente tiene el acceso mas limitado, enfocado en sus funcionalidades diarias. Puede registrar sesiones de clase, ver su historial de registros, ver su horario personal, ver y editar su perfil, y solicitar cambios de contrasena. No puede acceder a funcionalidades de gestion ni ver registros de otros docentes. Proteccion de Rutas: La proteccion de rutas se implementa a traves de los filtros de Shield. Cada grupo de rutas esta protegido por un filtro que verifica que el usuario este autenticado y pertenezca al grupo (rol) correcto. Las rutas de administrador solo son accesibles para usuarios con el grupo "admin", las rutas de coordinador solo para usuarios con el grupo "coordinador", y las rutas de docente solo para usuarios con el grupo "docente". Si un usuario intenta acceder a una ruta que no le corresponde, el sistema redirige a la pagina de acceso denegado. Proteccion contra Fuerza Bruta: El sistema implementa proteccion contra ataques de fuerza bruta tanto para el login por correo electronico como para el login por DNI. Se permiten un maximo de tres intentos fallidos consecutivos. Al agotar los tres intentos, la cuenta queda bloqueada temporalmente durante un periodo de cinco minutos. Durante este periodo, el usuario no puede intentar iniciar sesion nuevamente. Los intentos fallidos, los bloqueos y los accesos exitosos quedan registrados en la tabla de auditoria para fines de seguridad y monitoreo. Cuando un usuario inicia sesion exitosamente, se limpian los intentos pendientes asociados a su identificador. Gestion de Sesiones: Las sesiones de usuario se manejan a traves del sistema de sesiones nativo de CodeIgniter 4 integrado con Shield. Al cerrar sesion, se eliminan todos los datos de la sesion del servidor. El sistema valida la existencia de una sesion activa en cada peticion protegida. Las sesiones expiran automaticamente despues de un periodo de inactividad configurable en los archivos de configuracion del framework. SECCION 7: ESTRUCTURA DE BASE DE DATOS ---------------------------------------- La base de datos del sistema esta compuesta por 20 tablas interconectadas que cubren todas las necesidades de informacion del sistema. A continuacion se describe cada tabla y su proposito. Tabla users (Shield): Esta tabla es gestionada por la libreria Shield de CodeIgniter y almacena las cuentas de usuario basicas del sistema. Cada registro representa un usuario unico con un identificador numerico autoincremental. Los campos incluyen correo electronico, nombre de usuario, estado activo o inactivo, y marcas de tiempo de creacion y actualizacion. Es la tabla central de identidad y todas las demas tablas de datos personales se vinculan a ella. Tabla auth_identities: Tambien gestionada por Shield, esta tabla almacena las credenciales de autenticacion de cada usuario. Un usuario puede tener multiples identidades (por ejemplo, autenticacion por correo y por DNI). Cada identidad contiene el tipo (correo o DNI), el valor del identificador y el hash de la contrasena. Esta separacion permite que un mismo usuario tenga multiples formas de autenticarse. Tabla auth_groups_users: Esta tabla asigna usuarios a grupos, que en este sistema representan los roles. Cada registro vincula un user_id con el nombre de un grupo: "admin", "coordinador" o "docente". Un usuario puede pertenecer a un solo grupo en este sistema. Shield utiliza esta tabla para determinar los permisos de acceso del usuario. Tabla personal: Esta tabla almacena los datos personales detallados de cada usuario del sistema. Incluye el numero de DNI (con restriccion de unicidad), apellidos, nombres, fecha de nacimiento, genero (M, F, u Otro), numero de celular, telefono fijo, correo personal y direccion de domicilio. Se vincula a la tabla users mediante un user_id con clave foranea. La restriccion de unicidad en el campo user_id garantiza que un usuario tenga un solo registro de datos personales. Tabla programas: Esta tabla almacena los programas academicos de la institucion. Cada programa tiene un nombre y un estado activo o inactivo. Incluye un campo coordinador_personal_id que vincula al docente coordinador asignado al programa. La clave foranea hacia la tabla personal usa la accion SET NULL en eliminacion, lo que significa que si se elimina un registro de personal, el campo coordinador se establece en nulo en lugar de eliminar el programa. Tabla docentes: Esta tabla crea la identidad de docente dentro del sistema, vinculando un registro de personal con un programa academico. Cada registro tiene un personal_id unico (con restriccion de unicidad) y un programa_id opcional. La relacion con personal usa CASCADE en eliminacion, lo que significa que si se elimina un registro personal, tambien se elimina el registro de docente asociado. Tabla periodos_academicos: Almacena los periodos academicos o semestres. Cada periodo tiene un codigo identificador (como "2026-I"), una fecha de inicio, una fecha de fin, un indicador de si es el periodo actual y un estado activo. El campo es_actual permite identificar rapidamente el periodo en curso. Tabla cursos: Registra los cursos academicos disponibles. Cada curso tiene un codigo unico, un nombre, un ciclo (del I al X), creditos, horas de teoria y practica semanales, un tipo de materia (Teorico, Practico, Laboratorio o Virtual), un programa al que pertenece y un estado activo. La clave foranea hacia programas usa RESTRICT en eliminacion, lo que impide eliminar un programa si tiene cursos asociados. Tabla feriados: Almacena las fechas feriadas del calendario academico. Cada registro tiene una fecha unica, una descripcion y un indicador de si es laborable o no. Esto permite al sistema ajustar los calendarios de clases y evitar conflictos con dias festivos. Tabla horario_academico: Tabla de configuracion global del horario academico de la institucion. Almacena la hora de inicio y fin de la jornada laboral, los dias laborales configurados (usando el tipo SET de MySQL para permitir multiples valores), una tolerancia default en minutos y un indicador de si se usan franjas academicas. Esta tabla permite definir la estructura horaria general que afecta a todo el sistema. Tabla franjas_academicas: Define los bloques de tiempo individuales que componen la jornada academica. Cada franja tiene un nombre, duracion en minutos, hora de inicio, hora de fin, un tipo (hora_clase, recreo o almuerzo) y un estado activo. La restriccion de unicidad en hora_inicio evita la superposicion de franjas. Esta tabla se relaciona con los horarios para indicar a que franja pertenece cada clase. Tabla disponibilidad_docente: Registra la disponibilidad horaria de cada docente por dia de la semana. Cada registro indica el docente, el dia de la semana (como ENUM), la hora de inicio y fin, y un estado activo. Esta informacion se utiliza para planificar las asignaciones de horarios y evitar conflictos de programacion. Tabla asignaciones: Esta tabla es un punto central del modelo de datos. Vincula un curso, un docente y un periodo academico, creando la asignacion de un docente para impartir un curso en un periodo determinado. La restriccion de unicidad compuesta en curso_id, docente_id y periodo_id garantiza que un docente no pueda ser asignado dos veces al mismo curso en el mismo periodo. Almacena ademas la fecha de asignacion. Tabla horarios: Cada registro representa un horario especifico de clase. Vincula una asignacion con un dia de la semana, hora de inicio, hora de fin, un aula opcional, un estado activo y una franja academica opcional. Esta tabla es la que determina cuales son las clases programadas para cada dia. La clave foranea hacia asignaciones usa CASCADE en ambas operaciones. Tabla registros_sesion: Esta es la tabla central del sistema. Almacena cada registro diario de sesion de clase creado por un docente. Los campos incluyen el horario_id que identifica que clase se registro, la fecha de la clase, la hora de envio al sistema, el numero de semana del silabo, la actividad realizada, las tareas dejadas, observaciones, el estado del registro (en_tiempo o fuera_de_plazo), el estado de revision del coordinador (Pendiente, Aprobado u Observado), un comentario opcional del coordinador, y el dispositivo de origen (web o app). La restriccion de unicidad compuesta en horario_id y fecha_clase garantiza que cada clase solo pueda ser registrada una vez por dia. Tabla config_sistema: Tabla de configuracion del sistema con formato clave-valor. Cada registro tiene una clave unica, un valor y una descripcion opcional. Esta tabla almacena las configuraciones dinamicas del sistema como tolerancia de minutos, horas maximas diarias y dias de plazo para registros tardios. Al estar en la base de datos, estas configuraciones pueden cambiarse sin modificar codigo fuente. Tabla auditoria: Registra un historial completo de acciones en el sistema. Cada registro captura el usuario que realizo la accion, la tabla afectada, el tipo de accion (insercion, actualizacion, eliminacion, login, logout, login_fallido o bloqueo_cuenta), una descripcion del cambio, la fecha del evento y la direccion IP. La clave foranea hacia users usa SET NULL en eliminacion para preservar el registro de auditoria aunque se elimine el usuario. Tabla notificaciones: Almacena las notificaciones enviadas a los usuarios. Cada notificacion tiene un user_id, un titulo, un mensaje, un indicador de si fue leida y la fecha de envio. Las notificaciones se crean automaticamente cuando ocurren eventos relevantes como aprobaciones, rechazos o solicitudes. Tabla solicitudes_password: Gestiona las solicitudes de cambio de contrasena realizadas por los docentes. Cada solicitud tiene un user_id, un estado (pendiente, atendida o rechazada), un comentario opcional, la fecha de creacion y la fecha de atencion. Los docentes no pueden cambiar su contrasena directamente, por lo que deben crear una solicitud que sera revisada por el administrador. Tabla login_attempts: Registra los intentos de acceso al sistema para la proteccion contra fuerza bruta. Cada registro captura el identificador utilizado (correo o DNI), el tipo de login, la direccion IP, si fue exitoso, la fecha hasta la cual esta bloqueado el identificador (si aplica) y la fecha de creacion. Esta tabla es consultada antes de permitir un nuevo intento de acceso. Relaciones entre Tablas: Las relaciones siguen una cadena logica de dependencias. La tabla users es la raiz: personal depende de users, docentes depende de personal, asignaciones depende de cursos, docentes y periodos, horarios depende de asignaciones (y opcionalmente de franjas_academicas), registros_sesion depende de horarios. Programas es una entidad independiente que alimenta a cursos y docentes. Config_sistema y feriados son tablas de configuracion independientes. Auditoria, notificaciones y solicitudes_password dependen de users. Login_attempts es una tabla independiente de monitoreo de seguridad. SECCION 8: FUNCIONALIDADES POR ROL ------------------------------------- ADMINISTRADOR: El administrador tiene acceso total al sistema. Sus funcionalidades incluyen la gestion completa de usuarios: puede crear, listar, editar y eliminar usuarios de todos los tipos (administradores, coordinadores y docentes). Puede asignar programas academicos a coordinadores y docentes. Puede gestionar la configuracion del sistema, incluyendo el valor de tolerancia en minutos para la clasificacion de registros, las horas maximas diarias permitidas y los dias de plazo para registros tardios. Puede administrar periodos academicos: crear nuevos periodos, editar fechas, marcar un periodo como actual y activar o desactivar periodos. Puede gestionar programas academicos: crear nuevos programas, asignar coordinadores y activar o desactivar programas. Puede administrar las franjas academicas: definir los bloques de tiempo de la jornada (horas de clase, recreos, almuerzos) con sus horas correspondientes. Puede gestionar feriados: registrar fechas festivas y indicar si son laborables o no. Puede configurar el horario academico global: definir hora de inicio y fin de jornada, dias laborales y tolerancia default. Puede visualizar todos los registros de sesion de todos los docentes con filtros por docente, curso, periodo y estado. Puede acceder al registro completo de auditoria para monitorear todas las acciones realizadas en el sistema. Puede gestionar las solicitudes de cambio de contrasena de los docentes, aprobandolas o rechazandolas y estableciendo la nueva contrasena cuando corresponde. Puede exportar reportes en formatos PDF, Excel y CSV con filtros flexibles. COORDINADOR: El coordinador gestiona las actividades de su programa academico. Su panel de control muestra estadisticas filtradas por programa, incluyendo el numero de docentes con clases pendientes de revision. Puede gestionar los cursos de su programa: crear, editar y desactivar cursos, definiendo codigo, nombre, ciclo, creditos, horas y tipo. Puede administrar las asignaciones: vincular docentes con cursos en un periodo especifico. Puede gestionar los horarios de clase: programar los dias y horas para cada asignacion, indicando el aula y la franja academica. Puede administrar la disponibilidad docente: definir los horarios en que cada docente de su programa esta disponible para impartir clases. Puede revisar y aprobar o rechazar los registros de sesion de los docentes de su programa, pudiendo agregar comentarios observacionales cuando detecta inconsistencias. Puede visualizar un horario semanal consolidado que muestra todas las clases programadas para su programa. Puede exportar reportes especificos de su programa en multiples formatos. DOCENTE: El docente es el usuario principal del sistema en terminos de frecuencia de uso. Su experiencia comienza al iniciar sesion con su DNI y contrasena. Al acceder al sistema, visualiza un panel de control personal que muestra sus KPIs: clases del dia, clases registradas, clases pendientes, total de registros historicos, registros en tiempo y fuera de plazo, y porcentaje de cumplimiento personal. Puede ver sus clases del dia para saber que clases tiene programadas. Puede registrar una sesion de clase seleccionando una de sus clases programadas y completando el formulario con el tema del silabo, las actividades realizadas, las tareas dejadas y observaciones. El sistema valida que la clase no haya sido registrada previamente y que la hora actual sea posterior a la hora de fin de la clase. Puede ver su historial de registros pasados con filtros por fecha y estado. Puede visualizar su horario semanal personal con todas sus clases programadas. Puede ver y editar su perfil personal, actualizando datos de contacto como numero de celular, telefono fijo, correo personal y direccion. Puede solicitar un cambio de contrasena, lo cual genera una solicitud que sera revisada por el administrador. SECCION 9: FLUJO PRINCIPAL - REGISTRO DE SESION DIARIA -------------------------------------------------------- El registro de sesion diaria es la funcionalidad central del sistema. El flujo completo consta de los siguientes pasos: Paso 1 - Autenticacion: El docente accede al sistema mediante la pagina de login especifica para docentes, ingresando su numero de DNI y contrasena. El sistema verifica que las credenciales sean correctas y que la cuenta no este bloqueada por intentos fallidos previos. Si la autenticacion es exitosa, se crea una sesion de usuario y se redirige al panel de control. Paso 2 - Panel de Control: Al acceder al panel, el docente visualiza sus indicadores clave. El panel muestra cuantas clases tiene programadas para el dia actual, cuantas ya han sido registradas y cuantas quedan pendientes. Tambien muestra su porcentaje de cumplimiento historico y sus proximas clases. Paso 3 - Navegacion al Modulo de Registro: Desde el sidebar de navegacion, el docente selecciona la opcion "Registrar". HTMX carga el contenido del modulo de registro en el area principal sin recargar la pagina completa, proporcionando una transicion rapida y fluida. Paso 4 - Seleccion de Clase: El modulo de registro muestra las clases del dia que aun no han sido registradas. Cada clase se muestra con su nombre, codigo, hora de inicio, hora de fin y aula. El docente selecciona la clase que desea registrar. Paso 5 - Validacion Previa: El sistema ejecuta validaciones antes de mostrar el formulario. Primero, verifica que la clase seleccionada no tenga un registro existente para la fecha actual, usando la restriccion de unicidad de la base de datos. Segundo, valida que la hora actual del servidor sea posterior a la hora de finalizacion de la clase. Esta validacion evita registros futuros o prematuros. Si alguna validacion falla, el sistema muestra un mensaje de error al usuario. Paso 6 - Formulario de Registro: Si las validaciones pasan, se presenta un formulario con los siguientes campos: numero de semana del silabo (un valor numerico que indica en que semana del plan de estudios se encuentra la clase), actividad realizada (un campo de texto extenso donde el docente describe lo que se hizo en clase), tareas dejadas (un campo de texto opcional donde se detallan las tareas asignadas a los estudiantes), y observaciones (un campo opcional para notas adicionales). Paso 7 - Clasificacion Automatica: Al enviar el formulario, el sistema determina automaticamente el estado del registro. Obtiene la hora actual del servidor y la compara con la hora de finalizacion de la clase mas un valor de tolerancia configurable. Si la diferencia entre la hora de envio y la hora de fin de la clase es menor o igual a la tolerancia, el registro se clasifica como "en tiempo". Si la diferencia excede la tolerancia, se clasifica como "fuera de plazo". Esta clasificacion es automatica y no puede ser modificada manualmente. Paso 8 - Almacenamiento: El registro se guarda en la tabla registros_sesion con todos los datos capturados, la clasificacion automatica, el estado de revision inicial "Pendiente", la fecha de la clase y la hora exacta de envio al sistema. Se registra ademas un evento de auditoria con el tipo "insercion" y una descripcion que incluye el curso registrado y su estado. Paso 9 - Notificacion al Coordinador: El sistema crea una notificacion para el coordinador del programa al que pertenece el docente, informando que se ha recibido un nuevo registro de sesion pendiente de revision. Esta notificacion aparece en la campana de notificaciones del header del coordinador. Paso 10 - Revision del Coordinador: El coordinador accede a su modulo de registros y puede ver todos los registros pendientes de los docentes de su programa. Puede revisar la informacion registrada, agregar un comentario si detecta observaciones, y cambiar el estado a "Aprobado" o "Observado". Al tomar una accion, se crea una notificacion para el docente informandole la decision del coordinador. SECCION 10: SISTEMA DE AUDITORIA --------------------------------- El sistema de auditoria proporciona un registro completo e inmutable de todas las acciones significativas realizadas en el sistema. Cada evento de auditoria se almacena en la tabla auditoria con los siguientes datos: el identificador del usuario que realizo la accion, la tabla de base de datos afectada, el tipo de accion ejecutada, una descripcion textual del cambio realizado, la fecha y hora exacta del evento, y la direccion IP del cliente desde donde se origino la accion. Las acciones rastreadas incluyen cinco categorias principales. Las acciones de insercion registran cuando se crea un nuevo registro en cualquier tabla del sistema. Las acciones de actualizacion registran cuando se modifica un registro existente, incluyendo una descripcion que detalla que campos cambiaron. Las acciones de eliminacion registran cuando se elimina un registro del sistema. Las acciones de login registran cada vez que un usuario inicia sesion exitosamente. Las acciones de logout registran cada vez que un usuario cierra sesion. Adicionalmente, las acciones de login_fallido registran cada intento de acceso fallido, y las acciones de bloqueo_cuenta registran cuando una cuenta es bloqueada por exceso de intentos fallidos. El trait AuditLogger es la pieza central de este sistema. Este trait define un metodo protegido que cualquier controlador puede invocar pasando cuatro parametros: la tabla afectada, el tipo de accion, una descripcion del cambio y opcionalmente el ID del usuario (que por defecto toma el usuario autenticado). Internamente, el trait obtiene la conexion a la base de datos, obtiene la direccion IP del cliente desde el objeto request, y ejecuta una insercion en la tabla auditoria con todos los campos. Este trait se incluye en el controlador base, lo que lo hace automaticamente disponible en todos los controladores del sistema. Los eventos de login y logout se capturan a traves del sistema de eventos de Shield. Cuando un usuario inicia o cierra sesion, Shield dispara un evento que es escuchado por los controladores correspondientes, que invocan el trait AuditLogger para registrar el evento. Los eventos de login fallido y bloqueo de cuenta se registran directamente desde el trait LoginAttemptHandler, que se invoca desde los controladores de autenticacion. La pagina de auditoria del administrador permite visualizar todos los registros de auditoria con soporte para recarga dinamica via HTMX. Los registros se muestran en una tabla paginada que incluye el usuario, la tabla afectada, la accion, la descripcion, la fecha y la direccion IP. La paginacion se implementa con HTMX, lo que permite navegar entre paginas sin recargar la interfaz completa. SECCION 11: SISTEMA DE NOTIFICACIONES -------------------------------------- El sistema de notificaciones mantiene informados a los usuarios sobre eventos relevantes que ocurren en el sistema. Las notificaciones se crean programaticamente desde los controladores cuando ocurren acciones que requieren atencion de otros usuarios. Los eventos que generan notificaciones incluyen: cuando un docente registra una sesion (se notifica al coordinador), cuando un coordinador aprueba o rechaza un registro (se notifica al docente), cuando un docente solicita un cambio de contrasena (se notifica al administrador), y cuando un administrador atiende o rechaza una solicitud de contrasena (se notifica al docente). Las notificaciones se almacenan con un titulo descriptivo, un mensaje detallado y un indicador de leido o no leido. La fecha de envio se registra automaticamente con la marca de tiempo del servidor. En la interfaz de usuario, las notificaciones se presentan de dos formas. En el header del sistema, se muestra una campana de notificaciones con un indicador del numero de notificaciones no leidas. El usuario puede hacer clic en la campana para ver las notificaciones recientes. Ademas, existe una pagina de bandeja de notificaciones completa que muestra todas las notificaciones del usuario con paginacion, permitiendo marcar cada notificacion como leida. La actualizacion de la campana se realiza de forma dinamica usando HTMX. SECCION 12: DASHBOARD Y ESTADISTICAS -------------------------------------- El panel de control del sistema es la primera pantalla que ve el usuario despues de iniciar sesion. Su contenido se adapta automaticamente segun el rol del usuario autenticado, mostrando indicadores clave de rendimiento (KPIs) relevantes para cada tipo de usuario. Para el administrador, el dashboard muestra metricas globales de toda la institucion. El numero total de docentes registrados en el sistema, el total de cursos activos, el numero total de clases programadas para el dia actual (calculado a partir de los horarios que coinciden con el dia de la semana), el numero de registros completados hoy (sumando registros en tiempo y fuera de plazo), el numero de registros pendientes (clases de hoy menos registros completados), el desglose por tipo de registro (en tiempo y fuera de plazo), y el porcentaje de cumplimiento calculado como el ratio de registros completados sobre clases totales. Para el coordinador, el dashboard muestra metricas similares pero filtradas por su programa academico. Solo cuenta los docentes, cursos, clases y registros que pertenecen a su programa. Adicionalmente, incluye un indicador del numero de docentes pendientes de registrar sus clases del dia. Para el docente, el dashboard muestra metricas personales: sus clases del dia, cuantas ha registrado, cuantas pendientes, su total historico de registros, registros en tiempo y fuera de plazo, su porcentaje de cumplimiento personal, y informacion sobre su proxima clase pendiente. Todos los dashboards incluyen un grafico de barras que muestra la actividad de registros de los ultimos siete dias. El grafico tiene dos series de datos: registros en tiempo (barras de un color) y registros fuera de plazo (barras de otro color). Este grafico se renderiza usando Chart.js y se alimenta de datos JSON proporcionados por el endpoint de estadisticas del dashboard. La carga de datos del dashboard es dinamica: los KPIs y el grafico se cargan mediante solicitudes asincronas a los endpoints JSON del servidor, lo que permite actualizar las metricas sin recargar toda la pagina. SECCION 13: SISTEMA DE REPORTES --------------------------------- El sistema de reportes permite generar documentos exportables con la informacion de registros de sesion y actividad del sistema. Los reportes estan disponibles tanto para administradores como para coordinadores, con la diferencia de que los coordinadores solo ven datos de su programa. Formatos de Exportacion: El formato PDF es generado usando la libreria DomPDF. Los documentos PDF incluyen un encabezado con el nombre del sistema, los filtros aplicados al reporte y una tabla con los registros que cumplen los criterios seleccionados. Este formato es ideal para impresion y archivado fisico. El formato Excel es generado usando PhpSpreadsheet. Los archivos generados son compatibles con Microsoft Excel y otras aplicaciones de hojas de calculo. Incluyen las mismas columnas que el formato PDF pero con la ventaja de que los datos pueden ser filtrados, ordenados y analizados en la hoja de calculo. El formato CSV (valores separados por comas) es el formato mas basico y universalmente compatible. Puede ser importado en cualquier herramienta de datos, incluyendo Google Sheets, LibreOffice Calc y herramientas de analisis de datos. Filtros Disponibles: Los reportes pueden filtrarse por los siguientes criterios: docente especifico o todos los docentes, curso especifico o todos los cursos, periodo academico, rango de fechas (desde y hasta), estado de registro (en tiempo, fuera de plazo o todos), y estado de revision (pendiente, aprobado, observado o todos). Contenido del Reporte: Cada registro en el reporte incluye: nombre completo del docente, codigo y nombre del curso, fecha de la clase, hora de registro, estado de registro (en tiempo o fuera de plazo), estado de revision del coordinador y comentario del coordinador si existe. SECCION 14: PROTECCION CONTRA BRUTE-FORCE ------------------------------------------ El sistema implementa un mecanismo robusto de proteccion contra ataques de fuerza bruta, que es una tecnica de seguridad que consiste en probar combinaciones multiples de identificadores y contrasenas hasta encontrar una valida. Para prevenir este tipo de ataque, el sistema limita el numero de intentos fallidos permitidos y aplica un bloqueo temporal automatico. El mecanismo funciona de la siguiente manera. Cada vez que un usuario intenta iniciar sesion y la autenticacion falla, el sistema registra el intento en la tabla login_attempts, incluyendo el identificador usado (ya sea correo electronico o DNI), el tipo de login, la direccion IP del cliente y un indicador de exito (falso en este caso). Despues de cada intento fallido, el sistema consulta el numero de intentos fallidos recientes para ese identificador. Si se alcanzan tres intentos fallidos consecutivos, el sistema registra un bloqueo de cinco minutos. Durante este periodo, cualquier intento de acceso con ese identificador sera rechazado inmediatamente sin verificar la contrasena, y el usuario recibira un mensaje indicando que su cuenta esta bloqueada y el tiempo restante. El trait LoginAttemptHandler encapsula toda esta logica y es reutilizado por los controladores de autenticacion de ambos tipos (correo y DNI). El trait proporciona tres metodos: verificarBloqueo para consultar si un identificador esta bloqueado antes de permitir un intento, registrarIntentoFallido para registrar un intento fallido y verificar si se alcanza el limite, y registrarIntentoExitoso para limpiar los intentos pendientes despues de un acceso exitoso. Cada evento relevante se registra en la tabla de auditoria: los intentos fallidos se registran con la accion "login_fallido" incluyendo el numero de intento y los intentos restantes, y los bloqueos se registran con la accion "bloqueo_cuenta". Esto permite al administrador monitorear intentos de acceso sospechosos a traves de la pagina de auditoria. SECCION 15: SISTEMA DE SOLICITUDES DE PASSWORD ----------------------------------------------- Los docentes del sistema no tienen la capacidad de restablecer su contrasena de forma autonoma, ya que no utilizan correo electronico para autenticarse. En su lugar, el sistema implementa un flujo de solicitudes de cambio de contrasena que requiere aprobacion del administrador. Cuando un docente necesita cambiar su contrasena, accede a la seccion de solicitudes de password desde su perfil y crea una nueva solicitud. La solicitud se almacena en la tabla solicitudes_password con estado "pendiente" y una marca de tiempo de creacion. El administrador recibe una notificacion indicando que hay una solicitud pendiente. Desde su modulo de solicitudes, puede ver todas las solicitudes con su estado actual. Al atender una solicitud, el administrador ingresa la nueva contrasena que sera asignada al usuario y opcionalmente agrega un comentario. El estado de la solicitud cambia a "atendida" y se registra la fecha de atencion. Si el administrador decide rechazar la solicitud, cambia el estado a "rechazada" y puede agregar un comentario explicando el motivo. El docente recibe una notificacion con el resultado de su solicitud. Una vez que el administrador establece una nueva contrasena, el docente puede usarla para iniciar sesion en su proximo acceso al sistema. La contrasena se almacena de forma segura utilizando el mecanismo de hashing proporcionado por Shield, que utiliza el algoritmo bcrypt. SECCION 16: HTMX Y NAVEGACION SPA ----------------------------------- HTMX es una herramienta fundamental en la experiencia de usuario del sistema. Permite navegacion tipo aplicacion de pagina unica (SPA) sin la complejidad de un framework JavaScript frontend completo. En la practica, HTMX funciona de la siguiente manera en el sistema. Cuando el usuario hace clic en una opcion del sidebar de navegacion, HTMX intercepta el evento y envia una peticion HTTP GET al servidor usando la ruta definida en el atributo hx-get. La respuesta del servidor contiene un fragmento de HTML con solo el contenido de la vista solicitada, sin el layout completo. HTMX reemplaza el contenido del elemento identificado por hx-target (que es el area principal de la interfaz) con el HTML recibido. Simultaneamente, el atributo hx-push-url actualiza la URL del navegador en la barra de direccion, permitiendo el uso del boton de retroceso y la navegacion por historial. Esta funcionalidad depende de un mecanismo en el lado del servidor. El metodo renderView del controlador base verifica la presencia del encabezado HX-Request en cada peticion. Cuando el encabezado esta presente, el metodo retorna unicamente el contenido de la vista solicitada, sin envolverla en el layout principal. Cuando el encabezado no esta presente (como en una carga inicial de pagina), el metodo retorna la vista envuelta dentro del layout completo que incluye el sidebar, header y footer. Los beneficios de este enfoque son significativos. La navegacion entre secciones es perceptiblemente mas rapida porque solo se transfiere el contenido nuevo, no toda la pagina. No hay parpadeos ni recargas visibles. El sidebar y el header permanecen estaticos, proporcionando un contexto estable. Las tablas y formularios pueden actualizarse parcialmente sin afectar otros elementos de la pagina. Y todo esto se logra sin la complejidad de mantener un estado de aplicacion en el lado del cliente. HTMX tambien se utiliza para la paginacion dinamica de tablas, la recarga de contenido despues de acciones de formulario, la carga de modales de confirmacion y la actualizacion del contador de notificaciones en el header. SECCION 17: CONFIGURACION DEL SISTEMA -------------------------------------- Las configuraciones del sistema se almacenan en la tabla config_sistema de la base de datos, utilizando un formato flexible de clave-valor. Este enfoque permite modificar el comportamiento del sistema sin alterar codigo fuente, y facilita la administracion desde la interfaz web. La configuracion clave-valor funciona de la siguiente manera. Cada configuracion tiene una clave unica (como "tolerancia_minutos"), un valor textual (como "20"), y una descripcion opcional que explica su proposito. Los controladores del sistema consultan esta tabla para obtener los valores actualizados antes de ejecutar su logica. Tolerancia en Minutos (tolerancia_minutos): Este valor define cuantos minutos despues de la hora de finalizacion de una clase se sigue considerando que el registro esta "en tiempo". Por ejemplo, con un valor de 20 minutos, si una clase termina a las 10:50 y el docente registra la sesion a las 11:05, el registro se clasifica como "en tiempo" porque la diferencia es de 15 minutos, dentro de la tolerancia. Si el docente registra a las las 11:15, la diferencia es de 25 minutos, lo que excede la tolerancia y el registro se clasifica como "fuera de plazo". Este valor es configurable por el administrador. Horas Maximas Diarias (horas_maximas_diarias): Este valor establece el numero maximo de horas de clase que un docente puede tener asignadas en un solo dia. Se utiliza como referencia para la planificacion de horarios y puede generar advertencias cuando se intenta asignar mas horas de las permitidas. Dias de Plazo para Registro (dias_plazo_registro): Este valor define cuantos dias despues de la fecha de una clase se permite al docente realizar un registro tardio. Este mecanismo evita que se registren clases de periods muy antiguos, lo cual podria afectar la confiabilidad de los datos. Si un docente intenta registrar una clase cuya fecha excede este plazo, el sistema rechaza la operacion. SECCION 18: INSTALACION Y CONFIGURACION ---------------------------------------- La instalacion del sistema requiere un entorno de desarrollo o servidor con los siguientes requisitos previos: PHP version 8.2 o superior con las extensiones necesarias para CodeIgniter 4 (mbstring, xml, curl, gd, intl), Composer para la gestion de dependencias PHP, Node.js con npm para la compilacion de assets CSS, MySQL version 8.0 o superior, y Laragon (o cualquier servidor Apache compatible) como servidor web. El proceso de instalacion comienza con la clonacion del repositorio del proyecto en el directorio de trabajo del servidor web. Despues de clonar, se ejecuta la instalacion de dependencias PHP con Composer, que descarga e instala CodeIgniter 4, Shield, DomPDF, PhpSpreadsheet y todas las demas dependencias del backend. A continuacion, se instalan las dependencias de CSS con npm y se ejecuta la compilacion de Tailwind CSS para generar el archivo CSS optimizado que sera utilizado en produccion. El siguiente paso es configurar el archivo .env con los parametros de conexion a la base de datos (host, nombre de base de datos, usuario y contrasena), la configuracion del entorno (development o production), y la base URL del sitio. Una vez configurada la conexion, se crea la base de datos vacia y se ejecutan las migraciones de CodeIgniter para crear todas las tablas necesarias en el orden correcto, respetando las dependencias de claves foraneas. Despues de las migraciones, se ejecutan los seeders que pueblan la base de datos con datos iniciales de prueba, incluyendo usuarios de cada tipo, programas academicos, periodos, cursos, horarios y configuraciones del sistema. Finalmente, se configura un host virtual en el servidor web para apuntar al directorio public/ del proyecto y se verifica el acceso al sistema. Credenciales por Defecto: El sistema viene con credenciales de prueba predeterminadas. Para el acceso de administrador se usa el correo electronico admin@sistema.com con la contrasena "admin123". Para el acceso de coordinador se usa coord@sistema.com con la contrasena "coord123". Para el acceso de docente se usan los DNI de los docentes registrados en los seeders con la contrasena "docente123". Estas credenciales son de prueba y deben cambiarse en un entorno de produccion. SECCION 19: ESTRUCTURA DE ARCHIVOS ----------------------------------- El proyecto sigue la estructura de directorios estandar de CodeIgniter 4 con organizaciones adicionales para los roles del sistema. El directorio app/ es el nucleo de la aplicacion. Dentro de el se encuentran los siguientes subdirectorios principales. Config/ contiene todos los archivos de configuracion del framework: rutas, filtros, base de datos, autenticacion (Shield), sesiones, CORS y demas configuraciones del sistema. Controllers/ almacena los controladores PHP organizados por rol: un subdirectorio Admin/ con los controladores de administrador, un subdirectorio Coordinador/ con los controladores de coordinador, un subdirectorio Docente/ con los controladores de docente, y los controladores compartidos en el nivel raiz. Models/ contiene los modelos PHP que representan cada tabla de la base de datos. Views/ almacena las vistas PHP organizadas por rol, con subdirectorios Admin/, Coordinador/, Docente/ y compartidas. Database/Migrations/ contiene las migraciones que definen el esquema de la base de datos en orden cronologico. Database/Seeds/ contiene los seeders que pueblan la base de datos con datos iniciales. Traits/ contiene los traits reutilizables: AuditLogger para auditoria, DiaHelper para traduccion de dias, y LoginAttemptHandler para proteccion contra fuerza bruta. El directorio public/ es la raiz web accesible desde el navegador. Contiene los archivos CSS compilados de Tailwind, los archivos JavaScript de HTMX, Chart.js, SweetAlert2, GSAP y el codigo JavaScript personalizado del sistema, asi como los archivos de fuentes de Google Material Symbols y cualquier otro asset estatico. El directorio writable/ es utilizado por CodeIgniter para almacenar archivos generados en tiempo de ejecucion: cache de vistas, logs del sistema, sesiones de usuario y archivos temporales generados por la exportacion de reportes PDF y Excel. El directorio tests/ contiene las pruebas unitarias del sistema escritas con PHPUnit, el framework de pruebas integrado en CodeIgniter 4. Archivos de Configuracion Raiz: En la raiz del proyecto se encuentran archivos de configuracion importantes: composer.json para las dependencias PHP, package.json para las dependencias de Node.js, tailwind.config.js para la configuracion de Tailwind CSS, phpunit.dist.xml para la configuracion de pruebas, .env para las variables de entorno, y el archivo spark que es el punto de entrada de la linea de comandos de CodeIgniter. SECCION 20: CONVENCIONES Y BUENAS PRACTICAS --------------------------------------------- El sistema sigue un conjunto de convenciones y buenas practicas que garantizan la calidad, mantenibilidad y seguridad del codigo. Todos los textos de interfaz, mensajes de error, nombres de campos y etiquetas de la interfaz de usuario estan escritos en espanol, adaptado al contexto peruano. La zona horaria del sistema es UTC-5 (hora de Peru), lo que asegura que todas las fechas y horas mostradas sean consistentes con la localizacion del usuario. Las operaciones criticas de base de datos que involucran multiples tablas se ejecutan dentro de transacciones. Si alguna operacion dentro de la transaccion falla, todas las operaciones se revierten, manteniendo la consistencia de los datos. Esto es especialmente importante en operaciones como la creacion de registros de sesion, donde se debe garantizar que no existan registros duplicados. La integridad referencial se mantiene mediante claves foraneas en la base de datos. Las politicas de eliminacion y actualizacion en cascada estan cuidadosamente definidas para cada relacion. Por ejemplo, la eliminacion de un usuario personal cascada hacia su registro de personal y su registro de docente, mientras que la eliminacion de un programa solo se permite si no tiene cursos asociados (restriccion RESTRICT). Las rutas del sistema estan nombradas en el archivo de configuracion de rutas, lo que facilita la generacion de URLs y el mantenimiento. Cuando se necesita generar una URL en una vista o controlador, se utiliza el nombre de la ruta en lugar de la ruta literal, lo que permite cambiar las rutas sin afectar el codigo que las referencia. Las reglas de validacion de datos incluyen mensajes de error en espanol que explican de forma clara al usuario que datos debe proporcionar. Las validaciones se ejecutan tanto en el lado del servidor como en el disenio de los formularios, proporcionando retroalimentacion inmediata. Cada operacion de creacion, actualizacion o eliminacion genera un registro de auditoria que captura que cambio, quien lo hizo, cuando y desde donde. Este registro es inmutable y sirve como evidencia de todas las acciones realizadas en el sistema. Las configuraciones del sistema que pueden variar entre instituciones o periodos se almacenan en la base de datos en lugar de estar codificadas en archivos de configuracion. Esto permite a los administradores ajustar el comportamiento del sistema desde la interfaz web sin intervention tecnica. SECCION 21: TABLAS RESUMEN --------------------------- TABLA 1: CONTROLADORES DEL SISTEMA Nombre del Controlador | Espacio de Nombre | Proposito -------------------------------------|--------------------------|------------------------ BaseController | App\Controllers | Controlador base con | | metodos compartidos Dashboard | App\Controllers | Panel de control y | | estadisticas JSON Home | App\Controllers | Pagina de inicio NotificacionesController | App\Controllers | API de notificaciones LoginController (Auth) | App\Controllers\Auth | Login admin/coordinador LoginController (Docente) | App\Controllers\Docente | Login docente DashboardController (Coord) | App\Controllers\Coordinad | Dashboard coordinador RegistroController | App\Controllers\Docente | Registro de sesiones HistorialController | App\Controllers\Docente | Historial de registros ClasesController | App\Controllers\Docente | Clases del dia docente HorarioController (Docente) | App\Controllers\Docente | Horario personal PerfilController | App\Controllers\Docente | Perfil docente SolicitudPasswordController | App\Controllers\Docente | Solicitudes password UsuariosController | App\Controllers\Admin | Gestion de usuarios ProgramasController | App\Controllers\Admin | Gestion de programas PeriodosController | App\Controllers\Admin | Gestion de periodos ConfigController | App\Controllers\Admin | Config del sistema FranjasController | App\Controllers\Admin | Gestion de franjas FeriadosController | App\Controllers\Admin | Gestion de feriados HorarioAcademicoController | App\Controllers\Admin | Horario academico DocentesController (Admin) | App\Controllers\Admin | Gestion de docentes AuditoriaController | App\Controllers\Admin | Registro de auditoria SolicitudesController | App\Controllers\Admin | Solicitudes password RegistrosController (Admin) | App\Controllers\Admin | Registros de sesion ReportesController (Admin) | App\Controllers\Admin | Exportacion reportes CursosController | App\Controllers\Coordinad | Gestion de cursos AsignacionesController | App\Controllers\Coordinad | Gestion asignaciones HorariosController (Coord) | App\Controllers\Coordinad | Gestion horarios DocentesController (Coord) | App\Controllers\Coordinad | Docentes del programa DisponibilidadController | App\Controllers\Coordinad | Disponibilidad docente HorarioSemanalController | App\Controllers\Coordinad | Horario semanal RegistrosController (Coord) | App\Controllers\Coordinad | Registros de sesion ReportesController (Coord) | App\Controllers\Coordinad | Exportacion reportes TABLA 2: MODELOS DEL SISTEMA Nombre del Modelo | Tabla Asociada | Proposito ---------------------------------|-------------------------|------------------------ RegistroSesionModel | registros_sesion | Registros diarios de | | sesion de clase DocenteModel | docentes | Datos de docentes CursoModel | cursos | Cursos academicos HorarioModel | horarios | Horarios de clases AsignacionModel | asignaciones | Asignaciones | | curso-docente-periodo ProgramaModel | programas | Programas academicos PeriodoAcademicoModel | periodos_academicos | Periodos academicos FeriadoModel | feriados | Feriados FranjaAcademicaModel | franjas_academicas | Franjas horarias HorarioAcademicoModel | horario_academico | Config horaria global DisponibilidadModel | disponibilidad_docente | Disponibilidad docente ConfigSistemaModel | config_sistema | Config del sistema AuditoriaModel | auditoria | Registro de auditoria NotificacionModel | notificaciones | Notificaciones LoginAttemptsModel | login_attempts | Intentos de acceso SolicitudPasswordModel | solicitudes_password | Solicitudes password AuthModel | users/auth_identities | Autenticacion TABLA 3: TABLAS DE BASE DE DATOS Tabla | Descripcion -----------------------------|---------------------------------------------- users | Cuentas de usuario gestionadas por Shield auth_identities | Credenciales de autenticacion auth_groups_users | Asignacion de usuarios a grupos/roles personal | Datos personales de los usuarios programas | Programas academicos de la institucion docentes | Registro de docentes vinculados a personal periodos_academicos | Periodos o semestres academicos cursos | Cursos academicos disponibles feriados | Fechas feriadas del calendario horario_academico | Configuracion global de horario franjas_academicas | Bloques de tiempo de la jornada disponibilidad_docente | Disponibilidad horaria de docentes asignaciones | Asignaciones curso-docente-periodo horarios | Horarios especificos de clase registros_sesion | Registros diarios de sesion (tabla central) config_sistema | Configuracion clave-valor del sistema auditoria | Historial de acciones del sistema notificaciones | Notificaciones a usuarios solicitudes_password | Solicitudes de cambio de contrasena login_attempts | Intentos de acceso para brute-force TABLA 4: MATRIZ DE PERMISOS POR ROL Funcionalidad | Admin | Coordinador | Docente -------------------------------------|-------|-------------|-------- Gestionar usuarios | SI | NO | NO Configurar sistema | SI | NO | NO Gestionar periodos academicos | SI | NO | NO Gestionar programas | SI | NO | NO Gestionar franjas academicas | SI | NO | NO Gestionar feriados | SI | NO | NO Configurar horario academico | SI | NO | NO Ver auditoria | SI | NO | NO Atender solicitudes password | SI | NO | NO Ver todos los registros | SI | NO | NO Exportar reportes globales | SI | NO | NO Gestionar cursos | NO | SI | NO Gestionar asignaciones | NO | SI | NO Gestionar horarios | NO | SI | NO Gestionar disponibilidad | NO | SI | NO Ver docentes del programa | NO | SI | NO Revisar registros de sesion | NO | SI | NO Ver horario semanal | NO | SI | NO Exportar reportes del programa | NO | SI | NO Registrar sesion de clase | NO | NO | SI Ver historial personal | NO | NO | SI Ver horario personal | NO | NO | SI Ver/editar perfil personal | NO | SI | SI Solicitar cambio de contrasena | NO | NO | SI Ver clases del dia | NO | NO | SI TABLA 5: RESUMEN DE MIGRACIONES Migracion | Fecha --------------------------------------------------------|---------- CreatePersonalTable | 2026-06-09 CreateProgramasTable | 2026-06-09 CreateDocentesTable | 2026-06-09 CreatePeriodosAcademicosTable | 2026-06-09 CreateCursosTable | 2026-06-09 CreateFeriadosTable | 2026-06-09 CreateHorarioAcademicoTable | 2026-06-09 CreateFranjasAcademicasTable | 2026-06-09 CreateDisponibilidadDocenteTable | 2026-06-09 CreateAsignacionesTable | 2026-06-09 CreateHorariosTable | 2026-06-09 CreateRegistrosSesionTable | 2026-06-09 CreateConfigSistemaTable | 2026-06-09 CreateAuditoriaTable | 2026-06-09 CreateNotificacionesTable | 2026-06-09 CreateSolicitudesPasswordTable | 2026-06-18 AddFranjaIdToHorarios | 2026-06-21 CreateLoginAttemptsTable | 2026-07-12 AddLoginFailBloqueoToAuditoria | 2026-07-12 SECCION 22: PLANIFICACION POR SPRINTS (HISTORIAS DE USUARIO) -------------------------------------------------------------- El desarrollo del sistema se gestiono mediante un Product Backlog dividido en seis sprints, utilizando historias de usuario (HU) como unidad de trabajo. La estimacion de esfuerzo se realizo con la escala de Fibonacci adaptada a Puntos de Historia (Story Points): | Talla | Puntos | Tiempo Estimado (Dias) | | :--- | :--- | :--- | | XS | 1 | 0.5 | | S | 2 | 1.0 | | M | 3 | 2.0 | | L | 5 | 3.0 | | XL | 8 | 5.0 | A continuacion se detalla el alcance, las historias de usuario y el estado de implementacion de cada sprint. SPRINT 1: GESTION ADMINISTRATIVA ----------------------------------- Objetivo: Establecer la infraestructura basica y los modulos de gestion de datos maestros para la operacion academica. | Codigo | Historial de Usuario | Puntos | Tiempo | | :--- | :--- | :---: | :---: | | HU01 | Autenticacion del Coordinador | 2 | 1.0 | | HU02 | Gestion de Cursos y Periodos | 3 | 2.0 | | HU03 | Gestion de Cuentas de Docentes | 3 | 2.0 | | HU04 | Gestion de Horarios Academicos | 5 | 3.0 | | HU05 | Asignacion de Carga Horaria | 3 | 2.0 | | Total | | 16 SP | 10 Dias| Estado de Implementacion: - HU01 (Completo): Shield configurado con grupos admin/coordinador/ docente, login, registro, magic links y filtros por grupo. - HU02 (Completo): Admin\CursosController y Admin\PeriodosController con CRUD completo y validacion de fechas en periodos. - HU03 (Completo): Admin\DocentesController con CRUD completo; crea en cadena users -> personal -> docentes dentro de una transaccion. - HU04 (Completo): HorarioAcademicoController (singleton), Franjas, Feriados y Disponibilidad con CRUD completo. - HU05 (Completo): Admin\AsignacionesController y Admin\HorariosController con CRUD y deteccion de conflictos horarios por docente. SPRINT 2: OPERACION TRANSACCIONAL ----------------------------------- Objetivo: Habilitar las funcionalidades core del docente, centradas en el registro de sesiones y reglas de negocio temporales. | Codigo | Historial de Usuario | Puntos | Tiempo | | :--- | :--- | :---: | :---: | | HU06 | Autenticacion del Docente | 2 | 1.0 | | HU07 | Visualizacion de Clases del Dia | 3 | 2.0 | | HU08 | Consulta del Horario Semanal | 3 | 2.0 | | HU09 | Registro de Sesion Pedagogica | 5 | 3.0 | | HU10 | Validacion de Restriccion Horaria | 2 | 1.0 | | HU11 | Clasificacion Automatizada del Registro| 2 | 1.0 | | Total | | 17 SP | 10 Dias| Estado de Implementacion: - HU06 (Completo): Login con DNI + contrasena via Docente\LoginController; recuperacion y bloqueo por intentos manejados por Shield. - HU07 (Completo): Docente\ClasesController con endpoint clasesHoy() que devuelve JSON; vista cargada via HTMX/AJAX. - HU08 (Completo): Docente\HorarioController con matriz semanal por dia. - HU09 (Completo): Docente\RegistroController con formulario, validacion de contenido y store() con transaccion. - HU10 (Completo): Validacion en store() que compara hora_actual >= hora_fin_clase; endpoint verificar() para check en tiempo real. - HU11 (Completo): Clasificacion automatica en_tiempo / fuera_de_plazo usando tolerancia_minutos de config_sistema. SPRINT 3: MONITOREO Y SUPERVISION ----------------------------------- Objetivo: Proveer herramientas de analisis y visualizacion para el seguimiento del cumplimiento academico diario. | Codigo | Historial de Usuario | Puntos | Tiempo | | :--- | :--- | :---: | :---: | | HU12 | Indicadores visuales en panel docente | 2 | 1.0 | | HU13 | Historial de registros personales | 3 | 2.0 | | HU14 | Dashboard administrativo con metricas | 5 | 3.0 | | HU15 | Alertas de docentes pendientes | 3 | 2.0 | | HU16 | Panel de auditoria general | 3 | 2.0 | | Total | | 16 SP | 10 Dias| Estado de Implementacion: - HU12 (Completo): ClasesController devuelve stats; tarjetas de colores (azul total, verde en tiempo, rojo fuera de plazo, amarillo pendientes). - HU13 (Completo): HistorialController con filtros GET por curso y rango de fechas. - HU14 (Completo): Coordinador\DashboardController con estadisticasJson() (KPIs) y grafico Chart.js de barras apiladas de 7 dias. - HU15 (Completo): DashboardController::docentesPendientes() devuelve JSON de docentes con clases sin registrar (subconsulta NOT EXISTS). - HU16 (Completo): Coordinador\RegistrosController con filtros combinados y acciones aprobar/observar con comentario. SPRINT 4: SEGURIDAD Y REPORTES -------------------------------- Objetivo: Refinar la seguridad y habilitar la exportacion de informacion consolidada. | Codigo | Historial de Usuario | Puntos | Tiempo | | :--- | :--- | :---: | :---: | | HU17 | Motor de filtrado complejo para auditoria | 3 | 2.0 | | HU18 | Autogestion y recuperacion de credenciales | 3 | 2.0 | | HU19 | Configuracion de parametros globales | 3 | 2.0 | | HU20 | Generacion de reportes PDF y Excel | 5 | 3.0 | | Total | | 14 SP | 9 Dias | Estado de Implementacion: - HU17 (Completado): Filtros combinados en Admin\RegistrosController y Coordinador\RegistrosController, con paginacion. - HU18 (Completado): SolicitudPasswordController (docente solicita) + SolicitudesController (admin atiende) con flujo completo. - HU19 (Completado): ConfigController y HorarioAcademicoController para tolerancia, horas maximas, dias plazo, horario laboral y dias laborables. - HU20 (Completado): Exportacion CSV, PDF (Dompdf 3.1) y Excel (PhpSpreadsheet 5.8) con filtros combinados. Nota: En este sprint tambien se activo el sistema de auditoria (trait AuditLogger en app/Traits/AuditLogger.php) que registra automaticamente acciones criticas en la tabla auditoria desde los controladores. Resumen de puntos por sprint: S1=16, S2=17, S3=16, S4=14. Total del backlog: 63 Story Points. SECCION 23: CONCLUSIONES ------------------------- El sistema Parte Diario Docente representa una solucion integral para la gestion y control de las actividades academicas diarias en una institucion educativa. Su diseno basado en roles permite que cada tipo de usuario (administrador, coordinador y docente) acceda exclusivamente a las funcionalidades relevantes para su labor, manteniendo la seguridad y la claridad de la interfaz. La eleccion del stack tecnologico combina madurez y modernidad: CodeIgniter 4 proporciona un backend robusto y rapido, MySQL garantiza la integridad y consistencia de los datos academicos, y el conjunto de herramientas frontend (Tailwind CSS, HTMX, Chart.js, SweetAlert2, GSAP) ofrece una experiencia de usuario fluida y moderna sin la complejidad de un framework JavaScript de aplicacion completa. El patron MVC organiza el codigo de forma clara y mantenible, facilitando futuras ampliaciones como la incorporacion de una aplicacion movil, la integracion con sistemas de gestion academica existentes o la incorporacion de nuevos roles y funcionalidades. El sistema de auditoria completo y el registro detallado de intentos de acceso proporcionan trazabilidad y seguridad, aspectos fundamentales en un sistema que maneja informacion academica institucional. La arquitectura basada en HTMX para la navegacion parcial demuestra que es posible lograr una experiencia de usuario tipo SPA sin sacrificar la simplicidad del renderizado del lado del servidor, reduciendo la complejidad del frontend y mejorando el rendimiento general de la aplicacion. En conjunto, el sistema proporciona una herramienta valiosa para la gestion academica, facilitando el cumplimiento de los procesos de reporte docente, mejorando la visibilidad de las actividades en el aula, y proporcionando datos oportunos para la toma de decisiones institucionales. ===================================================== FIN DEL DOCUMENTO =====================================================