﻿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
=====================================================
