# SGETECBA - Documentacion Completa del Sistema

## 1. Resumen Ejecutivo

SGETECBA es un sistema de gestion estudiantil orientado a la operacion academica de TECBA. El sistema centraliza autenticacion, administracion de estudiantes, estructura academica, inscripciones, control de asistencia, seguimiento de ausencias, registro de abandono, importacion masiva desde Excel y reportes ejecutivos.

La base del sistema esta dividida en dos capas:

- Backend API con FastAPI, SQLAlchemy y Alembic.
- Frontend web con React, TypeScript, Vite y Tailwind CSS.

El foco funcional actual del sistema esta en:

- autenticacion y control de acceso por rol,
- dashboard institucional,
- consulta y gestion de estudiantes,
- configuracion academica,
- seguimiento de asistencia y ausencias,
- importacion masiva de estudiantes,
- reportes base para direccion y administracion.

## 2. Objetivo del Sistema

El objetivo de SGETECBA es apoyar la gestion academica y el seguimiento estudiantil mediante una plataforma unica que permita:

- administrar usuarios con permisos diferenciados,
- registrar y consultar estudiantes,
- organizar carreras, materias, horarios, grupos y gestiones,
- gestionar inscripciones evitando duplicidades,
- registrar asistencia por asignatura y fecha,
- detectar ausencias recurrentes,
- registrar abandonos con motivo y trazabilidad,
- importar estudiantes desde archivos Excel con validacion previa,
- consolidar indicadores para toma de decisiones.

## 3. Alcance Funcional

### 3.1 Modulos del backend

El backend expone los siguientes modulos bajo el prefijo `/api/v1`:

- `auth`: autenticacion y sesion.
- `students`: gestion de estudiantes.
- `academic`: catalogos y estructura academica.
- `attendance`: asistencia, lista y ausencias.
- `dropouts`: registro de abandono estudiantil.
- `imports`: importacion masiva de estudiantes desde Excel.
- `reports`: dashboard e indicadores.

### 3.2 Cobertura actual del frontend

El frontend implementado actualmente consume solo una parte del backend:

- login,
- dashboard,
- listado y busqueda de estudiantes.

Aunque el backend ya expone endpoints para academico, asistencia, importaciones y abandono, esas capacidades no estan completamente conectadas en la UI actual de `frontend/src/App.tsx`.

## 4. Arquitectura del Sistema

## 4.1 Arquitectura logica

```text
Usuario
  -> Frontend React/Vite
  -> API FastAPI (/api/v1)
  -> SQLAlchemy ORM
  -> Base de datos SQLite o PostgreSQL
```

## 4.2 Estructura del repositorio

```text
sgetecba/
|-- backend/
|   |-- app/
|   |   |-- api/
|   |   |-- core/
|   |   |-- database/
|   |   |-- models/
|   |   |-- schemas/
|   |   |-- security/
|   |   |-- services/
|   |   |-- main.py
|   |   `-- seed.py
|   |-- alembic/
|   |-- tests/
|   |-- requirements.txt
|   `-- .env
|-- frontend/
|   |-- src/
|   |   |-- components/
|   |   |-- services/
|   |   |-- types/
|   |   `-- App.tsx
|   |-- package.json
|   `-- .env.example
|-- database/
|   `-- sgetecba_schema_postgresql-18.05.2026.sql
|-- documentacion/
|   |-- archivos fuente de importacion y soporte
|   `-- SGETECBA_DOCUMENTACION_COMPLETA.md
|-- start_all.cmd
`-- start_all.ps1
```

## 4.3 Stack tecnologico

### Backend

- FastAPI
- Uvicorn
- SQLAlchemy 2
- Alembic
- Pydantic 2
- python-jose para JWT
- passlib/bcrypt para hashing de contrasenas
- Pandas y OpenPyXL para importaciones Excel
- pytest para pruebas

### Frontend

- React 18
- TypeScript
- Vite
- Tailwind CSS
- React Router DOM
- Recharts
- Lucide React

### Base de datos

Dos modos aparecen en el proyecto:

- modo actual local por defecto: SQLite (`sqlite:///./sgetecba.db`),
- modo preparado para despliegue: PostgreSQL mediante `.env.example`.

## 5. Configuracion y Entornos

## 5.1 Variables del backend

Variables relevantes del backend:

- `PROJECT_NAME`
- `API_V1_PREFIX`
- `SECRET_KEY`
- `ACCESS_TOKEN_EXPIRE_MINUTES`
- `DATABASE_URL`
- `FRONTEND_URL`
- `FIRST_SUPERUSER`
- `FIRST_SUPERUSER_PASSWORD`

### Estado actual observado

El archivo `backend/.env` usa por defecto:

- `DATABASE_URL=sqlite:///./sgetecba.db`
- `FRONTEND_URL=http://localhost:5173`
- usuario inicial `admin`
- contrasena inicial `admin123`

### Configuracion alternativa prevista

El archivo `backend/.env.example` esta preparado para PostgreSQL:

- servidor `postgres`
- puerto `5432`
- base `sgetecba`
- usuario `sgetecba_user`

## 5.2 Variables del frontend

El frontend usa:

- `VITE_API_URL=http://localhost:8000/api/v1`

Esto define la URL base del backend consumida desde `frontend/src/services/api.ts`.

## 6. Seguridad y Control de Acceso

## 6.1 Autenticacion

La autenticacion se basa en JWT Bearer Token.

Flujo:

1. El usuario envia `username` y `password` a `/api/v1/auth/login`.
2. El backend valida credenciales.
3. Si son correctas, devuelve `access_token`.
4. El frontend almacena el token en `localStorage`.
5. El frontend consulta `/api/v1/auth/me` para obtener el usuario actual.

## 6.2 Roles implementados

Los roles definidos en el modelo son:

- `ADMIN`
- `SECRETARIA`
- `DOCENTE`
- `DIRECCION`

## 6.3 Reglas de autorizacion

La autorizacion se aplica con `require_roles(...)` en el backend.

Ejemplos:

- `ADMIN`: acceso total a catalogos, asignaciones y usuarios operativos.
- `SECRETARIA`: alta de estudiantes, inscripciones e importaciones.
- `DOCENTE`: consulta sus asignaciones y registra asistencia.
- `DIRECCION`: acceso a reportes y seguimiento institucional.

Si el usuario no tiene permisos suficientes, la API responde `403`.

## 7. Modelo de Datos

## 7.1 Catalogos y seguridad

- `roles`: roles del sistema.
- `users`: usuarios autenticables del sistema.
- `teachers`: docentes asociados opcionalmente a un usuario.

## 7.2 Entidades estudiantiles

- `students`: informacion general del estudiante.
- `enrollments`: inscripcion de estudiante a una asignacion academica.
- `attendance`: registro de asistencia por fecha.
- `absences`: tabla derivada de ausencias o justificaciones.
- `dropouts`: registro formal de abandono.
- `dropout_reasons`: catalogo de motivos de abandono.

## 7.3 Estructura academica

- `careers`: carreras.
- `academic_levels`: niveles academicos.
- `schedules`: horarios.
- `groups`: grupos.
- `academic_terms`: gestiones o periodos academicos.
- `subjects`: asignaturas.
- `course_assignments`: combinacion de materia, docente, horario, grupo y gestion.

## 7.4 Importaciones y auditoria

- `excel_import_batches`: lotes de importacion.
- `excel_import_errors`: errores detectados en preview.
- `audit_logs`: bitacora de acciones operativas.

## 7.5 Enumeraciones del sistema

### Estado del estudiante

- `inscrito`
- `activo`
- `no_activo`
- `abandono`

### Estado de inscripcion

- `inscrito`
- `activo`
- `retirado`
- `finalizado`

### Estado de asistencia

- `Presente`
- `Falta`
- `Atraso`
- `Justificado`

### Tipo de nivel academico

- `anual`
- `semestral`
- `modular`

### Turno

- `manana`
- `tarde`
- `noche`

### Estado de importacion

- `preview`
- `imported`
- `failed`

## 7.6 Reglas de integridad relevantes

- `users.username` es unico.
- `teachers.email` es unico cuando existe.
- `students.codigo_estudiante` y `students.ci` son unicos.
- `course_assignments` evita duplicar la misma combinacion de materia, docente, horario, grupo y gestion.
- `enrollments` evita duplicar la inscripcion del mismo estudiante a la misma asignacion.
- `attendance` evita duplicar asistencia por inscripcion y fecha.
- `absences` mantiene una sola ausencia por registro de asistencia.

## 8. Reglas de Negocio Clave

## 8.1 Estudiantes

- No se puede crear un estudiante con el mismo `codigo_estudiante` o `ci`.
- El listado de estudiantes permite busqueda por nombre, apellido, CI o codigo.

## 8.2 Inscripciones

- No se permite inscribir dos veces al mismo estudiante en la misma asignacion academica.
- Las inscripciones son gestionadas por `ADMIN` y `SECRETARIA`.

## 8.3 Asistencia

- Un docente solo puede registrar asistencia sobre asignaciones que le pertenecen.
- La asistencia se registra por lote para una asignacion y fecha.
- `Falta` y `Justificado` se integran con el seguimiento de ausencias.

## 8.4 Abandono

- Registrar un abandono cambia el estado del estudiante al valor indicado.
- Al registrar abandono, el estudiante queda `is_active = False`.
- El abandono requiere motivo y usuario responsable.

## 8.5 Importacion Excel

- La importacion de estudiantes es de dos pasos: `preview` y `commit`.
- El archivo debe contener al menos:
  - `codigo_estudiante`
  - `nombres`
  - `apellidos`
  - `ci`
- En preview se detectan:
  - columnas faltantes,
  - filas con datos obligatorios vacios,
  - duplicados contra estudiantes ya existentes.
- Solo las filas sin errores y no duplicadas se insertan en el commit.

## 8.6 Auditoria

Se registra bitacora en acciones como:

- crear estudiante,
- editar estudiante,
- crear carrera,
- crear horario,
- crear grupo,
- crear docente,
- crear gestion,
- crear asignatura,
- crear asignacion,
- crear inscripcion,
- registrar abandono,
- preview de importacion,
- commit de importacion.

## 9. API del Sistema

Todos los endpoints estan bajo `/api/v1`.

## 9.1 Salud

### `GET /health`

Valida que la API este levantada.

Respuesta:

```json
{
  "status": "ok",
  "service": "sgetecba"
}
```

## 9.2 Autenticacion

### `POST /api/v1/auth/login`

Entrada:

```json
{
  "username": "admin",
  "password": "admin123"
}
```

Salida:

```json
{
  "access_token": "jwt_token",
  "token_type": "bearer"
}
```

### `GET /api/v1/auth/me`

Devuelve el usuario autenticado y su rol.

## 9.3 Estudiantes

### `GET /api/v1/students`

Lista estudiantes. Permite `?search=texto`.

### `POST /api/v1/students`

Crea estudiante. Roles: `ADMIN`, `SECRETARIA`.

### `GET /api/v1/students/{student_id}`

Consulta detalle de un estudiante.

### `PUT /api/v1/students/{student_id}`

Actualiza un estudiante. Roles: `ADMIN`, `SECRETARIA`.

## 9.4 Academico

### Catalogos de consulta

- `GET /api/v1/academic/levels`
- `GET /api/v1/academic/careers`
- `GET /api/v1/academic/schedules`
- `GET /api/v1/academic/groups`
- `GET /api/v1/academic/teachers`
- `GET /api/v1/academic/terms`
- `GET /api/v1/academic/subjects`
- `GET /api/v1/academic/assignments`
- `GET /api/v1/academic/enrollments`

### Altas administrativas

- `POST /api/v1/academic/careers`
- `POST /api/v1/academic/schedules`
- `POST /api/v1/academic/groups`
- `POST /api/v1/academic/teachers`
- `POST /api/v1/academic/terms`
- `POST /api/v1/academic/subjects`
- `POST /api/v1/academic/assignments`
- `POST /api/v1/academic/enrollments`

Roles principales:

- catalogos: usuario autenticado,
- altas estructurales: normalmente `ADMIN`,
- inscripciones: `ADMIN` y `SECRETARIA`.

## 9.5 Asistencia

### `GET /api/v1/attendance/teacher-assignments`

Devuelve asignaciones accesibles para docente, admin o direccion.

### `GET /api/v1/attendance/roster`

Parametros:

- `assignment_id`
- `attendance_date`

Devuelve la lista de inscritos para registrar o revisar asistencia.

### `POST /api/v1/attendance/bulk`

Registra asistencia masiva por asignacion y fecha.

Roles:

- `ADMIN`
- `DOCENTE`

### `GET /api/v1/attendance/absences`

Resumen de ausencias con filtros opcionales:

- `assignment_id`
- `start_date`
- `end_date`

Incluye alerta cuando el total de faltas es mayor o igual a 3.

## 9.6 Abandono

### `GET /api/v1/dropouts/reasons`

Lista motivos de abandono activos.

### `GET /api/v1/dropouts`

Lista abandonos registrados.

### `POST /api/v1/dropouts`

Registra un abandono. Roles:

- `ADMIN`
- `SECRETARIA`
- `DIRECCION`

## 9.7 Importaciones

### `POST /api/v1/imports/students/preview`

Recibe archivo Excel y devuelve:

- identificador del lote,
- totales,
- duplicados,
- errores,
- detalle fila por fila.

### `POST /api/v1/imports/students/{batch_id}/commit`

Confirma la importacion del lote validado.

Roles:

- `ADMIN`
- `SECRETARIA`

## 9.8 Reportes

### `GET /api/v1/reports/dashboard`

Parametros opcionales:

- `start_date`
- `end_date`

Roles:

- `ADMIN`
- `DIRECCION`
- `SECRETARIA`

Devuelve:

- KPIs generales,
- distribucion por sexo,
- estudiantes por carrera,
- abandono por motivo,
- asistencia por asignatura.

## 10. Frontend

## 10.1 Funcionalidades implementadas

El frontend actual entrega:

- pantalla de login,
- persistencia de token,
- restauracion de sesion,
- dashboard con KPI y graficos,
- buscador y tabla de estudiantes,
- layout lateral institucional,
- cierre de sesion.

## 10.2 Flujo de autenticacion del frontend

1. Se muestran por defecto las credenciales iniciales.
2. `loginRequest` consume `/auth/login`.
3. El token se guarda en `localStorage` bajo la clave `sgetecba_token`.
4. `fetchCurrentUser` consulta `/auth/me`.
5. La aplicacion habilita el dashboard si el usuario es valido.

## 10.3 Servicios del frontend

Archivo principal de consumo API:

- `frontend/src/services/api.ts`

Capacidades actuales:

- login,
- obtener usuario actual,
- obtener dashboard,
- listar estudiantes.

## 10.4 Limitaciones actuales del frontend

- no hay gestion visual completa para academico,
- no hay UI conectada para asistencia,
- no hay UI conectada para abandono,
- no hay UI conectada para importaciones Excel,
- el menu actual no refleja todo el backend disponible,
- la navegacion aun no aplica menus diferentes por rol en la UI actual.

## 11. Proceso de Importacion de Estudiantes

## 11.1 Entrada esperada

Archivo Excel con columnas normalizadas:

- `codigo_estudiante`
- `nombres`
- `apellidos`
- `ci`

Columnas opcionales soportadas:

- `sexo`
- `telefono`
- `correo`
- `direccion`
- `observacion`

## 11.2 Flujo operativo

1. Subir archivo a `preview`.
2. Revisar errores, duplicados y filas validas.
3. Confirmar lote con `commit`.
4. Insertar solo filas aptas.
5. Registrar auditoria.

## 11.3 Salidas de control

El sistema guarda:

- lote de importacion,
- payload de preview,
- errores por fila,
- conteo de insertados,
- conteo de duplicados,
- conteo de errores.

## 12. Reportes e Indicadores

El dashboard consolida actualmente:

- total de estudiantes,
- estudiantes activos,
- estudiantes inactivos,
- cantidad de abandonos,
- inscripciones activas,
- ausencias del dia o de la fecha final filtrada.

Graficos:

- estudiantes por sexo,
- estudiantes por carrera,
- abandonos por motivo,
- asistencia por asignatura.

## 13. Semilla Inicial del Sistema

El script `backend/app/seed.py` crea automaticamente:

- roles del sistema,
- niveles academicos,
- grupos base `A` y `B`,
- motivos de abandono comunes,
- usuario administrador inicial,
- docente demo,
- usuario demo de docente.

Credenciales observadas:

- `admin / admin123`
- `docente / docente123`

## 14. Instalacion y Puesta en Marcha

## 14.1 Backend local

Desde `backend/`:

```powershell
.\\venv314\\Scripts\\python.exe -m uvicorn app.main:app --host localhost --port 8000
```

## 14.2 Frontend local

Desde `frontend/`:

```powershell
& 'C:\Program Files\nodejs\npm.cmd' run build
& 'C:\Program Files\nodejs\npm.cmd' run preview -- --host localhost --port 5173
```

## 14.3 Script conjunto

El archivo `start_all.ps1` intenta lanzar:

- backend en `http://localhost:8000`
- frontend en `http://localhost:5173`

## 14.4 Docker

El backend tiene `Dockerfile` funcional con este flujo:

1. instala dependencias del sistema,
2. instala `requirements.txt`,
3. ejecuta `alembic upgrade head`,
4. ejecuta `python -m app.seed`,
5. levanta Uvicorn en `0.0.0.0:8000`.

No se encontro un `docker-compose.yml` operativo en la raiz del proyecto.

## 15. Pruebas y Validacion Ejecutadas

Durante esta revision se validaron:

- prueba automatizada `backend/tests/test_health.py`: correcta,
- build de frontend con Vite: correcto,
- generacion de `dist/` de frontend: correcta.

Resultado observado:

- `pytest`: 1 prueba aprobada,
- `vite build`: correcto, con advertencia por bundle mayor a 500 kB.

## 16. Estado Actual del Proyecto

## 16.1 Lo que esta operativo a nivel de backend

- autenticacion JWT,
- consulta de usuario actual,
- CRUD base de estudiantes,
- catalogos academicos,
- alta de asignaciones e inscripciones,
- control de asistencia,
- resumen de ausencias,
- registro de abandono,
- importacion Excel en dos pasos,
- dashboard de reportes,
- auditoria de acciones.

## 16.2 Lo que esta operativo a nivel de frontend

- login,
- dashboard,
- listado de estudiantes.

## 16.3 Lo que esta parcialmente implementado

- uso de PostgreSQL preparado pero no activo por defecto,
- soporte de despliegue parcial sin orquestacion completa,
- backend mas amplio que la capa visual actual.

## 16.4 Riesgos o brechas tecnicas actuales

- la UI no expone aun todos los modulos del backend,
- la configuracion por defecto local usa SQLite y puede diferir del despliegue esperado en PostgreSQL,
- el bundle principal del frontend es grande y deberia partirse,
- falta una documentacion operativa previa consolidada, ahora resuelta por este archivo,
- no se identifico una suite amplia de pruebas funcionales o integrales.

## 17. Recomendaciones Tecnicas

### Prioridad alta

- completar el frontend para asistencia, importaciones, academico y abandono,
- definir un `docker-compose.yml` con backend, frontend y PostgreSQL,
- unificar el entorno objetivo para evitar divergencia entre SQLite y PostgreSQL,
- ampliar pruebas sobre autenticacion, estudiantes, importaciones y reportes.

### Prioridad media

- implementar menu dinamico por rol en la UI,
- agregar paginacion y filtros avanzados en estudiantes,
- agregar exportacion de reportes,
- agregar trazabilidad visual de auditoria.

### Prioridad baja

- optimizar el bundle del frontend con code splitting,
- agregar dashboards mas detallados por carrera, docente o gestion,
- incorporar monitoreo y logging estructurado.

## 18. Credenciales y URLs de Referencia

### URLs

- backend health: `http://localhost:8000/health`
- backend API base: `http://localhost:8000/api/v1`
- frontend: `http://localhost:5173`

### Credenciales semilla

- administrador: `admin / admin123`
- docente demo: `docente / docente123`

## 19. Conclusiones

SGETECBA ya cuenta con una base backend funcional y relativamente amplia para la gestion estudiantil, con reglas de negocio importantes ya resueltas: autenticacion por rol, no duplicidad en inscripciones, importacion validada en dos pasos, acoplamiento entre asistencia y ausencias, registro de abandono y reportes institucionales.

El punto principal pendiente no es la capa API sino la consolidacion operativa del sistema completo: terminar la interfaz para todos los modulos, unificar el entorno de base de datos objetivo y fortalecer pruebas end-to-end. Aun asi, la base actual es suficiente para continuar una implementacion real del sistema sin rehacer la arquitectura principal.
