Documentación Backend - Música y Maestro¶

Este directorio contiene documentación técnica para desarrolladores (backend y frontend).

📚 Documentación para Frontend¶

API Endpoints¶

Get Paginated Students - Endpoint para obtener estudiantes paginados
Request/Response
Ejemplos de uso en React/TypeScript
Casos de uso prácticos
Nueva propiedad renews explicada
Filtro de Renovación (renews) - Filtrar estudiantes por renovación
Parámetro renews=true|false
Ejemplos con tabs y dropdowns
Dashboard de estadísticas
Combinación con otros filtros
Bolsa de Horas (Hours Bank) - ✨ NUEVO: Gestión de horas de empleados
API Frontend - Endpoints y ejemplos
Arquitectura - Documentación técnica v2
Usuarios (v2) - Onboarding (create-password) y login
Notificaciones (v2) - Registro/actualización/eliminación de tokens push

🔧 Changelogs Técnicos (Para Backend)¶

2025-10-02¶

Implementación de propiedad `renews` en getPaginatedStudents ¶

Resumen: Implementación de una nueva propiedad renews que indica si un estudiante tiene matrículas activas en el curso escolar actual.

Archivos modificados: - GetPaginatedStudentsUseCase.ts - StudentRepositoryImpl.ts - DomainStudentRepository.ts - student.controller.ts - app.ts

Conceptos clave: - Patrón de obtener último curso escolar en casos de uso - LEFT JOIN con required: false en Sequelize - Propiedades opcionales para no romper compatibilidad - Cálculo de propiedades contextuales en controladores

Convenciones de Nomenclatura¶

Los archivos de sesión siguen el formato:

SESSION_YYYY-MM-DD_nombre-descriptivo.md

Ejemplo:

SESSION_2025-10-02_getPaginatedStudents_renews.md

Patrones de Arquitectura Documentados¶

1. Obtención del Último Curso Escolar¶

Patrón establecido: Obtener el último curso en el Caso de Uso, no en el repositorio.

Ubicación: Múltiples casos de uso - GetScheduleEmployeeByIdUseCase - GetRegistersByStudetUseCase - GetAttendanceRecordsByStudentIdUseCase - GetDashboardStudentUseCase

Implementación:

if(!schoolCourseId){
    const schoolCourse = await this.schoolCourseRepository.getLastCourse();
    schoolCourseId = schoolCourse?.getId();
}

Estructura del Proyecto¶

backend-musica-maestro/
├── src/
│   ├── application/
│   │   └── use-cases/          # Casos de uso (lógica de negocio)
│   ├── domain/
│   │   ├── entities/           # Entidades de dominio
│   │   └── repositories/       # Interfaces de repositorios
│   ├── infrastructure/
│   │   ├── adapters/
│   │   │   ├── mappers/        # Mappers infra <-> dominio
│   │   │   └── persistence/    # Implementaciones de repositorios
│   │   └── controllers/        # Controladores HTTP
│   └── models/                 # Modelos Sequelize
├── docs/                       # Documentación de sesiones (este directorio)
└── tests/                      # Tests

Decisiones de Arquitectura¶

Inyección de Dependencias¶

Las dependencias se inyectan en src/app.ts y se pasan a los controladores.

Ejemplo:

// Repositorios
const studentRepository = new StudentRepositoryImpl(appEventRepository);
const schoolCourseRepository = new SchoolCourseRepositoryImpl();

// Casos de uso
const getPaginatedStudentsUseCase = new GetPaginatedStudentsUseCase(
    studentRepository, 
    schoolCourseRepository
);

// Controladores
const studentController = new StudentController(
    getStudentByIdUseCase,
    // ... otros casos de uso
    getPaginatedStudentsUseCase
);

Compatibilidad Retroactiva¶

Al agregar nuevas propiedades a interfaces existentes: - ✅ Usar propiedades opcionales (?) - ✅ Documentar en README de sesión - ✅ No romper contratos existentes

Mappers¶

Los mappers transforman entre capas: - Infra → Dominio: toDomain() - Dominio → Response: .toJSON() en entidades

Recursos Útiles¶

Repositorios Importantes¶

Repositorio	Ubicación	Métodos Clave
`SchoolCourseRepository`	`infrastructure/adapters/persistence/`	`getLastCourse()`
`StudentRepository`	`infrastructure/adapters/persistence/`	`getPaginatedStudents()`
`RegistrationRepository`	`infrastructure/adapters/persistence/`	`getRegistersByStudentId()`
`HoursBankRepository`	`infrastructure/adapters/persistence/`	`getByEmployeeAndCourse()`, `findOrCreate()`

Utilidades¶

Función	Ubicación	Descripción
`getLastCourse()`	`utils/getLastCourse.ts`	Consulta directa a BD (no usado en dominio)
`catchAsync()`	`utils/catchAsync.ts`	Wrapper para manejo de errores
`AppError`	`utils/appError.ts`	Clase para errores personalizados

Contribuir a la Documentación¶

Cuando realices cambios importantes:

Crear archivo de sesión:

touch docs/SESSION_YYYY-MM-DD_nombre-descriptivo.md

Usar la plantilla:
Problema inicial
Cambios implementados
Decisiones de diseño
Archivos modificados
Testing recomendado
Actualizar este README:
Agregar entrada en "Índice de Sesiones"
Documentar nuevos patrones si aplica

Mantenimiento¶

Este directorio debe mantenerse: - ✅ Actualizado con cada sesión importante - ✅ Organizado cronológicamente - ✅ Con enlaces funcionales - ✅ Con ejemplos de código claros

Compartir Documentación con Frontend¶

Opción 1: GitHub/GitLab (Recomendado)¶

Si el proyecto está en un repositorio Git:

# Frontend puede acceder directamente a:
https://github.com/usuario/repo/blob/main/docs/API_FRONTEND_getPaginatedStudents.md

Ventajas: - ✅ Siempre actualizado - ✅ Control de versiones - ✅ Fácil de enlazar

Opción 2: Wiki/Notion/Confluence¶

Copia el contenido de API_FRONTEND_getPaginatedStudents.md
Pégalo en tu wiki corporativa
Comparte el enlace con el equipo de frontend

Opción 3: Slack/Email¶

Para Slack:

📚 Nueva documentación API: Get Paginated Students

Hola equipo de frontend,

He actualizado el endpoint de estudiantes paginados con una nueva propiedad `renews`.

📖 Documentación completa:
- Ver archivo: `docs/API_FRONTEND_getPaginatedStudents.md` en el repo
- O adjunto el archivo en este mensaje

✨ Cambios principales:
- Nueva propiedad `renews: boolean` (indica si renueva matrícula)
- Ejemplos de uso en React/TypeScript
- Casos de uso prácticos

¿Preguntas? Escríbanme por aquí 👋

Opción 4: Postman/Swagger¶

Si usas Postman o Swagger:

Importa el endpoint en Postman
Agrega la documentación en la sección "Description"
Comparte la colección con el equipo

Opción 5: Archivo PDF/Word¶

# Convertir Markdown a PDF usando pandoc
pandoc docs/API_FRONTEND_getPaginatedStudents.md -o getPaginatedStudents_API.pdf

# Enviar por email o compartir en Drive

Estructura de Archivos¶

docs/
├── README.md                                          # Este archivo (índice general)
├── API_FRONTEND_getPaginatedStudents.md              # 📚 Para Frontend
├── API_FRONTEND_renews_filter.md                     # 📚 Para Frontend
├── CHANGELOG_2025-10-02_student_renews_property.md   # 🔧 Para Backend
├── blocks/                                            # 📁 Documentación de bloques
├── fichaje/                                           # 📁 Documentación de fichaje
└── hours-bank/                                        # 📁 Bolsa de horas
    ├── README.md                                      # Índice del módulo
    ├── API_FRONTEND.md                               # 📚 Para Frontend
    └── ARCHITECTURE.md                               # 🔧 Para Backend

Para Frontend: Solo necesitan leer archivos API_FRONTEND_*.md
Para Backend: Leer todos los archivos (especialmente CHANGELOG_*.md)

Última actualización: 2025-12-04