# Plan de implementación: navegación académica contextual

Fecha: 2026-10-08. Estado: propuesta, sin implementación funcional.

## 1. Diagnóstico verificado en el código

- La aplicación usa SvelteKit, TypeScript, Drizzle y mysql2.
- Hay rutas de sedes, docentes, asignaturas, estudiantes y grados/grupos. Solo grados tiene una ruta de detalle.
- Las tarjetas de docentes y asignaturas y las filas de estudiantes no enlazan a detalles.
- El detalle de grado muestra asignaturas/docentes y matrículas en dos paneles.
- Los contadores existentes muestran sedes, asignaturas del grupo y registros de matrícula cargados. No hay agregaciones de indicadores por sede.
- Los enlaces generados con `withYear` conservan el año; el selector global vuelve al inicio y el enlace de cabecera no conserva el año.
- El repositorio relaciona curso, asignaturas y matrículas mediante año, grado y curso. El directorio docente mezcla adscripción actual y carga académica del año seleccionado.
- El esquema de lectura no incluye notas ni una identidad de estudiante independiente de la matrícula. El identificador expuesto como estudiante es `matriculados.row_id`.
- Las pruebas existentes comprueban rutas, aislamiento de sede/año y conteos de matrículas. No se ejecutaron durante este análisis documental.

Fuentes: `src/lib/server/db/schema.ts`, `src/lib/server/repositories/escolar.ts`, `src/lib/types/escolar.ts`, `src/lib/navigation.ts`, `src/routes`, `src/lib/components` y `tests/routes.test.mjs`.

## 2. Experiencia propuesta

Mantener tarjetas y navegación sin menú lateral. Añadir una cabecera de contexto con sede y año, breadcrumbs, indicadores enlazables y accesos a las secciones relacionadas.

| Punto de entrada | Detalle propuesto | Continuación |
| --- | --- | --- |
| Sede | Grados, grupos, docentes con carga, asignaturas y matrículas | Abrir cualquiera de esos conjuntos filtrados |
| Docente | Asignaturas agrupadas por grado y grupo; indicadores de carga | Asignatura del grupo, estudiantes de ese grupo y notas de esa asignatura |
| Datos del curso | Resumen y pestañas Asignaturas, Estudiantes y Docentes | Detalle de asignatura, docente o matrícula |
| Asignatura | Grupo, docente(s), matrícula del grupo y acceso a calificaciones | Estudiante, notas, docente y curso |
| Estudiante | Matrícula seleccionada, grupo, asignaturas y notas | Asignatura, docente y curso |

El contexto del docente limitará inicialmente sus estudiantes a los grupos donde tiene carga. La vista de notas conservará la asignatura seleccionada. No se interpretará navegar por un docente como iniciar sesión con su identidad.

Cada nombre relacionado tendrá un enlace explícito. Los indicadores abrirán la lista que explica su cifra. Las pantallas de detalle tendrán acciones como «Ver grupo», «Ver estudiantes» y «Ver notas», según los datos disponibles.

## 3. Contadores y significado

| Ámbito | Indicadores propuestos |
| --- | --- |
| Inicio, tarjeta de sede | Grados distintos, grupos, docentes con carga, asignaturas distintas y matrículas |
| Sede | Los mismos indicadores con acceso a sus listas |
| Docente | Grados, grupos, materias distintas, asignaciones a grupos y matrículas atendidas sin repetir una matrícula por materia |
| Curso/grupo | Asignaturas del grupo, docentes distintos y matrículas por estado |
| Asignatura en un grupo | Matrículas del grupo; con nota y sin nota, cuando se valide el modelo de evaluación |
| Matrícula del estudiante | Asignaturas; registros de notas por período, una vez validado su significado |

Reglas propuestas:

1. Distinguir grado de grupo: un grado puede tener varios cursos/grupos.
2. Distinguir materias distintas de asignaciones por grupo. Verificar que el código identifique la misma materia antes de agruparlo entre cursos.
3. Contar matrículas por su identidad verificada. No presentar ese total como personas únicas mientras no se valide una clave estable de estudiante y su relación con las matrículas.
4. Separar docentes con carga en el año de docentes adscritos actualmente. No presentar adscripción actual como adscripción histórica.
5. Mantener inicialmente todos los estados de matrícula, como hace el código actual, y permitir filtrarlos. La definición de matrícula activa queda pendiente de confirmar.
6. Calcular agregados independientes o preagrupados para evitar que unir materias, matrículas y notas multiplique los totales.
7. Sin año seleccionado, mostrar «Selecciona un año», no un cero académico. Un error de carga tampoco se representará como cero.
8. Totales y listas usarán los mismos filtros; con paginación se mostrará el total del conjunto, no solo el tamaño de la página.

## 4. Navegación y rutas

Conservar las rutas actuales de grados para compatibilidad y presentar su detalle como «Datos del curso» cuando corresponda.

Rutas nuevas propuestas, relativas a `/sedes/[sedeId]`:

- `/docentes/[docenteId]`: carga y grupos del docente.
- `/asignaturas/[asignaturaId]`: asignatura concreta del grupo y año.
- `/estudiantes/[matriculaId]`: expediente de esa matrícula, sin asumir identidad permanente de persona.
- `/asignaturas/[asignaturaId]/notas`: calificaciones filtradas por período y, opcionalmente, matrícula.

El año seguirá en `ano`. Pestaña, período, búsqueda, estado y paginación tendrán parámetros de URL cuando proceda. Los vínculos relacionados conservarán solo filtros aplicables al destino. El botón Atrás recuperará filtros y posición mediante el comportamiento de navegación implementado y probado.

Al cambiar de año se intentará conservar sede y sección. Los identificadores dependientes del año se resolverán únicamente con una correspondencia verificada; si no existe, se abrirá la lista de la sección con un mensaje explicativo.

Los breadcrumbs representarán una jerarquía estable. Para conservar el recorrido transversal se ofrecerá un enlace contextual de regreso, construido con rutas internas validadas.

## 5. Diseño visual propuesto

- Conservar la base verde institucional, fondos claros y tipografía actual; compactar la cabecera para dar prioridad a datos y navegación.
- Tarjetas de sede con nombre, ubicación e indicadores; tarjetas de docente con resumen de carga y acción visible.
- Encabezados de detalle con título, contexto y una fila de indicadores. Pestañas con cantidad, por ejemplo «Asignaturas (total)» y «Estudiantes (total)».
- Tablas para listas extensas en escritorio y filas/tarjetas adaptadas en móvil. Evitar convertir cada registro en una tarjeta grande.
- Búsqueda y filtros junto a la lista, con opción de restablecerlos.
- Estados diferenciados: sin carga docente, sin matrícula, sin calificación, sin coincidencias y error de consulta.
- Foco de teclado visible, etiquetas accesibles, contraste verificable y estado activo que no dependa solo del color.
- Sin cifras ficticias ni gráficos decorativos. Los indicadores serán accesos a datos comprobables.

## 6. Fases de implementación

### Fase 1. Verificar el contrato de datos

Inspeccionar metadatos de la base en modo lectura. Localizar tablas de notas, claves de estudiante/matrícula, asignatura, año y período; comprobar duplicados y cardinalidad de los enlaces. Verificar materias compartidas entre códigos/grupos, asignaturas optativas y si toda matrícula del grupo recibe todas sus materias.

Entregable: diccionario de relaciones y reglas de conteo. No generar migraciones con el esquema parcial.

Pendiente de verificar: origen de notas, escala, períodos, ponderación, recuperación, publicación y significado de valores nulos o cero. No calcular promedios ni niveles de desempeño sin estas reglas.

### Fase 2. Repositorio de lectura y contadores

Añadir contratos tipados de resumen y detalle. Implementar agregados por sede y por entidad, validadores de pertenencia y consultas parametrizadas. Mantener separados conteo total y consulta paginada.

Consultar indicadores de varias sedes en lotes, evitando una consulta por tarjeta. Examinar planes de consulta antes de proponer índices; cualquier cambio de estructura se tratará aparte del mapeo parcial.

Entregable: cifras reconciliables con las listas y consultas de detalle reutilizables.

### Fase 3. Navegación contextual y primeras pantallas

Ampliar `src/lib/navigation.ts` y breadcrumbs. Crear componentes de contexto, indicadores y pestañas. Añadir contadores a inicio/sede y detalle docente. Convertir curso en un detalle con vistas de asignaturas, docentes y estudiantes. Añadir enlaces cruzados en componentes existentes.

Entregable: recorrido Sede → Docente → Asignatura del grupo → Matrículas, y Curso → Asignaturas/Estudiantes, con regreso contextual.

### Fase 4. Detalles de asignatura y matrícula

Añadir rutas y cargas del servidor. Implementar filtros, búsqueda y paginación del servidor para conjuntos extensos. Validar cada entidad contra la sede y el año solicitados.

Entregable: navegación completa entre docentes, cursos, asignaturas y matrículas, accesible desde cualquiera de las secciones.

### Fase 5. Consulta de notas

Depende del contrato verificado en fase 1. Incorporar tabla por estudiante y período, y consulta individual por matrícula/asignatura. Distinguir cero de ausencia de nota. Mostrar valores almacenados y calcular derivados solo con reglas confirmadas.

La aplicación actual no incluye autenticación ni roles. Si las notas se habilitan para acceso compartido, definir usuarios y permisos en servidor antes de exponerlas. Filtrar una pantalla por docente no sustituye autorización.

Entregable: recorrido Docente → Asignatura/grupo → Estudiante → Notas, con período y contexto conservados.

### Fase 6. Verificación

- Ejecutar `npm run check`, `npm run build` y las pruebas existentes mediante RTK.
- Ampliar pruebas de aislamiento para docente, asignatura, matrícula y notas.
- Comparar contadores con consultas independientes y sus listas filtradas.
- Comprobar docente que enseña varias materias al mismo grupo, docente sin carga, materias sin docente y matrículas en diferentes estados.
- Verificar ausencia de notas, nota cero, períodos, cambios de año y enlaces directos.
- Probar recorridos completos, Atrás, recarga y teclado en móvil, tableta y escritorio.
- Medir consultas y tiempos con el volumen real antes de fijar objetivos de rendimiento.

## 7. Criterios de aceptación

1. Desde un docente se accede a sus asignaturas y grupos; desde cada asignatura/grupo a sus matrículas y a las notas correspondientes.
2. Desde Datos del curso se cambia entre asignaturas, estudiantes y docentes sin perder sede ni año.
3. Las entidades relacionadas tienen enlaces válidos de ida y regreso; los detalles se pueden abrir directamente por URL.
4. Cada indicador coincide con la lista que abre y explica qué cuenta.
5. El servidor rechaza entidades que no pertenecen al contexto solicitado.
6. Las notas conservan su significado real; no se inventan períodos, promedios o umbrales.
7. Las pantallas son utilizables por teclado y en tamaños móvil, tableta y escritorio.

## 8. Aclaraciones pendientes

- Confirmar dónde están almacenadas las notas, si no se identifican inequívocamente al inspeccionar la base.
- Confirmar cuáles estados de matrícula deben considerarse activos y si deben ser el filtro inicial.
- Definir quién consultará las notas y con qué alcance si se amplía el uso local actual.

Estas decisiones condicionan notas, totales de activos y permisos. Las mejoras de navegación y conteos de registros existentes pueden avanzar de forma independiente.