Intranet Despertares — API Backend

API REST del proyecto Intranet Despertares (colegio): backend en Spring Boot 3 y Java 17+ que sirve a los portales web (landing, backoffice, admin, profesores, padres, estudiantes). Autenticación con AWS Cognito, archivos en AWS S3, correos con AWS SES. Base de datos PostgreSQL en el servidor.

---

Descripción general

• Alcance: Intranet estilo LMS (Blackboard): gestión académica, notas, asistencia, tareas con entregas y adjuntos, material por clase, anuncios, agenda virtual (mérito/demérito), calendario (eventos por tareas), noticias públicas, notificaciones por email (agenda y nota publicada), pagos, horarios.
• Arquitectura: Híbrida. En AWS solo Cognito, S3 y SES. La API y PostgreSQL corren en un servidor (VPS/EC2).
• Base path: /api. Documentación OpenAPI/Scalar en /api/scalar.html (en dev).

Roles y portales

Rol	Descripción principal
ADMIN	Usuarios, pagos, horarios, secciones, vínculos padre–estudiante, SUNAT (consulta RUC/DNI).
EDITOR / Backoffice	Noticias (crear, aprobar, rechazar), imágenes, notificaciones.
TEACHER	Clases asignadas, notas, asistencia, tareas (CRUD), archivos por clase, anuncios, agenda, calendario.
PARENT	Hijos, notas de hijos, pagos propios, anuncios y agenda de hijos, calendario por hijo.
STUDENT	Notas propias, clases, tareas y entregas (con adjuntos), archivos de clase, anuncios, agenda, calendario.

Rutas principales (prefijo /api)

Módulo	Prefijo	Ejemplos
Auth	/auth	GET /me
Admin	/admin	/users, /payments, /schedules, /sections, /parent-students, /sunat/consulta
Backoffice	/backoffice	/news, /images, /notifications
Teacher	/teacher	/classes, /classes/{id}/grades, /classes/{id}/tasks, /classes/{id}/agenda, /calendar
Student	/student	/classes, /grades, /tasks, /announcements, /agenda, /calendar, /files
Parent	/parent	/children, /children/{id}/grades, /children/{id}/agenda, /children/{id}/calendar, /payments
Público	/public/news	Listado de noticias aprobadas (sin auth).

---

Requisitos

• Java 17 o superior
• PostgreSQL (para perfiles dev, staging, prod)
• Maven 3.9+ (o wrapper ./mvnw)

---

Levantar en desarrollo

1. Base de datos: crea una base PostgreSQL (ej. despertares_dev): createdb despertares_dev
2. Variables de entorno: ver tabla en Arquitectura. Sin Cognito/S3/SES, login, archivos y emails no estarán disponibles.
3. Migraciones Flyway: con perfil dev se aplican al arrancar.
4. Arrancar: ./mvnw spring-boot:run → API en http://localhost:8080/api, docs en http://localhost:8080/api/scalar.html

---

Perfiles

Perfil	Uso
dev	Desarrollo local: PostgreSQL local, CORS amplio, docs públicas.
test	Tests: H2 en memoria, Flyway desactivado.
staging / prod	BD y AWS reales; en prod, rate limiting activo.

---

Tests

./mvnw test

---

Backup y restauración

• ./scripts/backup-db.sh — vuelco a archivo local.
• ./scripts/restore-db.sh — restaura desde .sql.
• ./scripts/backup-db-and-upload-s3.sh — backup + subida S3 (cron VPS).

Detalle: Operación backup/restore y Backups automáticos VPS + S3.

---

Documentación (esta wiki)

Usa el índice de la izquierda para navegar por: Arquitectura, Modelo de datos, Cognito, Backups, Cobertura funcional, Notificaciones, Despliegue y Próximas mejoras.