Manual Técnico

TimeSchool es una aplicación web full-stack con renderizado en servidor. Toda la lógica de negocio vive en el servidor; el cliente recibe HTML hidratado o respuestas JSON.

Todas las variables se definen en .env.local (desarrollo) o en los secrets de Vercel/Railway (producción). Ninguna variable SUPABASE_SERVICE_ROLE_KEY o GEMINI_API_KEY debe exponerse al cliente.

# ── Base de datos ────────────────────────────────────────────────────
DATABASE_URL=postgresql://...@pooler.supabase.com:6543/postgres?pgbouncer=true
# Usado por Prisma Migrate y prisma db push (session mode, sin pgbouncer)
DIRECT_URL=postgresql://...@db.supabase.com:5432/postgres

# ── Supabase Auth ─────────────────────────────────────────────────────
NEXT_PUBLIC_SUPABASE_URL=https://<project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...   # Clave pública — OK en cliente
SUPABASE_SERVICE_ROLE_KEY=eyJ...       # ⚠ Solo servidor — NUNCA al cliente

# ── IA ────────────────────────────────────────────────────────────────
GEMINI_API_KEY=AIza...                 # ⚠ Solo servidor

# ── Email (prioridad: Resend > Gmail > SMTP > Console) ────────────────
RESEND_API_KEY=re_...
GMAIL_USER=centro@gmail.com
GMAIL_APP_PASSWORD=xxxx xxxx xxxx xxxx
SMTP_HOST=mail.ies.es
SMTP_PORT=587
SMTP_USER=noreply@ies.es
SMTP_PASS=...
SMTP_SECURE=false
EMAIL_FROM=noreply@timeschool.es

# ── App ───────────────────────────────────────────────────────────────
NEXT_PUBLIC_SITE_URL=https://timeschool.es
NEXT_PUBLIC_APP_URL=https://timeschool.es

TimeSchool usa PostgreSQL alojado en Supabase con Prisma 7 como ORM. El adaptador @prisma/adapter-pg permite usar el pooler de Supabase (pgbouncer en transaction mode) sin cambiar la sintaxis de Prisma.

Tablas del sistema

Convenciones generales

IDs: todos usan cuid() (Collision-resistant Unique ID). Seguro para URLs, sin colisiones entre entornos. Excepción: SchedulingConfig.id = "default" (singleton).

Timestamps: createdAt DateTime @default(now()) en casi todos los modelos. updatedAt DateTime @updatedAt en entidades que cambian frecuentemente (Teacher, Schedule, TimeFrame, Department, SchedulingConfig).

Soft delete: Teacher usa isActive Boolean @default(true). No hay borrado lógico en otras entidades.

JSON fields: availability, preferredHours (Teacher), breaks, dayOverrides (TimeFrame) se almacenan como Json de PostgreSQL. Validación a nivel de aplicación, no de BBDD.

Prisma genera enums de PostgreSQL nativos. Cambiar un valor de enum en producción requiere migración manual.

Tabla central del sistema. Unifica la ficha académica del profesor con sus credenciales de acceso (Supabase Auth) y su rol RBAC. Un registro Teacher puede existir antes de que el profesor tenga cuenta de acceso (authUserId = null).

Índices

@@index([email]) · @@index([role]) · @unique en email y authUserId

Define una asignatura académica con sus parámetros de scheduling. La relación con grupos de clase es N:M a través de SubjectClassGroup (join table explícita). La relación con el profesor "por defecto" es directa, pero puede sobrescribirse por grupo en SubjectClassGroup.teacherId.

Representa un grupo de clase (ej. 1ºA ESO). Es la unidad central del scheduling junto con Teacher y Subject. Cada slot del horario pertenece a una Lesson que referencia uno o más ClassGroups.

Espacio físico del centro. El scheduler asigna aulas a las Lessons según el roomType de la Subject. Un Room puede aparecer en múltiples Lessons simultáneas en ciclos de semana distintos (A/B), pero no en el mismo día/hora.

Una Lesson es la unidad de programación: agrupa quién enseña qué a quién y dónde. Es un modelo N:M que permite representar desdobles, codocencia y grupos mixtos sin duplicar datos.

// Caso simple: 1 profesor · 1 asignatura · 1 grupo · 1 aula
Lesson {
  teachers:    [AnaGarcía]
  subjects:    [Matemáticas]
  classGroups: [1ºA ESO]
  rooms:       [Aula 12]
}

// Desdoble: mismo grupo dividido en dos subgrupos simultáneos
Lesson {
  teachers:    [ProfeA, ProfeB]
  subjects:    [Inglés, Inglés]
  classGroups: [2ºA ESO]
  rooms:       [Aula 3, Aula 5]
}

// Grupo mixto / optativa
Lesson {
  teachers:    [ProfeC]
  subjects:    [TIC]
  classGroups: [4ºA ESO, 4ºB ESO]   // alumnos de dos grupos
  rooms:       [Aula Informática 1]
}

Schedule — Instancia de horario

ScheduleSlot — Posición temporal de una Lesson

Un ScheduleSlot responde a "¿cuándo?" ocurre una Lesson dentro de un Schedule. Toda información sobre quién, qué, dónde está en la Lesson y sus relaciones N:M.

Restricción única

@@unique([scheduleId, dayOfWeek, startHour, lessonId])
// Un schedule no puede tener la misma lesson dos veces el mismo día a la misma hora.
// No impide que dos lessons distintas coincidan (colisión detectada por la app, no por la BBDD).

Absence — Ausencia de profesor

Substitution — Guardia asignada

SupervisionZone y BreakSupervision

SchedulingConfig — Singleton de pesos SA

Siempre existe exactamente un registro con id = "default". Los pesos van de 0 (ignorar) a 5 (restricción casi dura).

TimeFrame — Marco horario

El diagrama a continuación muestra las relaciones principales. Las líneas sólidas son FK directas; las punteadas son N:M implícitas gestionadas por Prisma.

Teacher ──1:N──► Subject          (teacherId → Subject.teacherId)
Teacher ──1:N──► ClassGroup       (como tutor: tutorId)
Teacher ──N:M──► Lesson           (tabla implícita _LessonToTeacher)
Teacher ──N:M──► Department       (a través de DepartmentMembership)
Teacher ──1:N──► Absence          (AbsentTeacher)
Teacher ──1:N──► Substitution     (OriginalTeacher + SubstituteTeacher)
Teacher ──1:N──► BreakSupervision
Teacher ──1:N──► SubjectClassGroup (override de profesor por grupo)

Subject ──N:M──► ClassGroup       (a través de SubjectClassGroup)
Subject ──N:M──► Lesson           (tabla implícita _LessonToSubject)
Subject ──N:M──► SubjectBlock     (tabla implícita _SubjectToSubjectBlock)
Subject ──N:1──► Department       (departmentId)

ClassGroup ──N:1──► TimeFrame     (timeFrameId)
ClassGroup ──N:1──► Room          (aula base: roomId)
ClassGroup ──N:M──► Lesson        (tabla implícita _ClassGroupToLesson)
ClassGroup ──N:M──► SubjectBlock  (tabla implícita _ClassGroupToSubjectBlock)

Lesson ──1:N──► ScheduleSlot     (lessonId)
Lesson ──N:M──► Room             (tabla implícita _LessonToRoom)
Lesson ──N:M──► Student          (tabla implícita _LessonToStudent)

Schedule ──1:N──► ScheduleSlot   (scheduleId, Cascade)
Schedule ──1:N──► BreakSupervision (scheduleId, Cascade)

Absence ──1:N──► Substitution    (absenceId, Cascade)

Department ──1:N──► Subject      (departmentId, SetNull)
Department ──1:N──► DepartmentMembership (Cascade)

SupervisionZone ──1:N──► BreakSupervision (Cascade)

Tablas N:M implícitas generadas por Prisma

Flujo de autenticación

1. Usuario envía credenciales → Supabase Auth
2. Supabase devuelve JWT → se almacena en cookie httpOnly
3. proxy.ts (middleware Next.js) intercepta CADA petición:
   a. Refresca la cookie con createServerClient(@supabase/ssr)
   b. Verifica si la ruta es pública (PUBLIC_PATHS)
   c. Si no hay sesión y ruta privada → redirect /login
   d. Si hay sesión y es /login → redirect /
4. Server Components/Route Handlers llaman a getAuthSession():
   a. Obtiene el user de Supabase Auth
   b. resolveTeacher(): busca Teacher WHERE authUserId = user.id
      AND isActive = true. Si no existe vínculo, intenta el JIT-link
      (ver sección siguiente); el email NUNCA se usa para un usuario
      ya vinculado.
   c. Devuelve AuthSession { authUserId, email, teacherId, name, role }
5. Funciones guard aplican RBAC:
   requireAuth()   → cualquier profesor activo
   requireStaff()  → ADMIN o DIRECTIVO
   requireAdmin()  → solo ADMIN

JIT Linking (Just-In-Time)

El primer inicio de sesión vincula automáticamente auth.users.id → Teacher.authUserId buscando por email. Condiciones: el email del usuario debe estar confirmado en Supabase (email_confirmed_at), y debe existir un Teacher activo con ese email sin authUserId previo. El update es condicionado y atómico (updateMany), de modo que dos logins simultáneos no pueden producir un doble vínculo, y un Teacher ya vinculado a otra cuenta nunca puede ser reclamado por email.

Esto permite que el admin cree fichas de profesor antes de que ellos hagan login, sin necesidad de preconfigurar nada en Supabase.

Guards disponibles

Row Level Security (RLS)

Supabase tiene RLS habilitado a nivel de PostgreSQL. Las políticas aseguran que un profesor con role = TEACHER solo puede leer sus propios datos aunque tenga acceso directo a la BBDD. La aplicación usa el SERVICE_ROLE_KEY (bypass RLS) únicamente en Server Components y Route Handlers autenticados.

Cliente Prisma singleton

// lib/prisma.ts
import { PrismaClient } from '@prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

function createPrismaClient() {
  const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! })
  return new PrismaClient({ adapter, log: ['warn', 'error'] })
}

// Patrón singleton para evitar múltiples conexiones en dev (hot reload)
const globalForPrisma = globalThis as unknown as { prisma: PrismaClient }
export const prisma = globalForPrisma.prisma ?? createPrismaClient()
if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma

Patrón de uso en Route Handlers

// Ejemplo: GET /api/teachers
import { prisma } from '@/lib/prisma'
import { requireAuthApi } from '@/lib/auth/session'

export async function GET() {
  const { session, error } = await requireAuthApi()
  if (error) return error  // 401/403 automático

  const teachers = await prisma.teacher.findMany({
    where:   { isActive: true },
    orderBy: { name: 'asc' },
    select:  { id: true, name: true, email: true, role: true }
  })
  return Response.json(teachers)
}

// Ejemplo: PATCH con mutación
export async function PATCH(req: Request, { params }: { params: { id: string } }) {
  const { session, error } = await requireStaffApi()  // ADMIN o DIRECTIVO
  if (error) return error

  const body = await req.json()
  const teacher = await prisma.teacher.update({
    where: { id: params.id },
    data:  body
  })
  return Response.json(teacher)
}

Services layer

Bajo /services hay una capa de servicio que encapsula lógica de negocio compleja (ej. guardService.ts para scoring de sustitutos, scheduleService.ts para generación). Los Route Handlers delegan en los services y solo manejan HTTP.

Comandos de BBDD

# Desarrollo: sincronizar schema sin migraciones
npm run db:push       # prisma db push (destructivo si hay cambios de tipo)

# Producción: usar migraciones versionadas
npm run db:migrate    # prisma migrate dev --name <nombre>

# Introspección visual
npm run db:studio     # Abre Prisma Studio en localhost:5555

# Seed con datos de demo (IES Villa de Aspe)
npm run seed          # npx tsx prisma/seed.ts

Todas las rutas viven bajo app/api/. Siguen REST con Next.js Route Handlers. Responden siempre JSON. El patrón de error estándar es { "error": "mensaje" }.

Fase 1 — Greedy MRV (Generación inicial)

Implementado en algorithms/scheduler.ts. Genera el horario desde cero.

1. Construir lista de "assignments" (lesson × group × semana)
2. Ordenar por MRV: menor número de slots válidos disponibles primero
3. Para cada assignment:
   a. Calcular slots válidos (sin colisión de teacher/group/room/disponibilidad)
   b. Elegir el slot con menor penalización (heurística greedy)
   c. Asignar y bloquear ese slot para las siguientes iteraciones
4. Los assignments no resueltos se reportan como "unresolved"

Complejidad: O(n × m) donde n = assignments, m = slots posibles

Fase 2 — Simulated Annealing (Optimización)

Implementado en algorithms/simulatedAnnealing.ts. Toma el horario generado y lo mejora iterativamente.

Parámetros:
  T_inicial = 100.0      // Temperatura inicial
  T_final   = 0.1        // Temperatura final
  α (alpha) = 0.995      // Factor de enfriamiento geométrico
  iterations = saIterations (config)

Por cada iteración:
  1. Proponer movimiento aleatorio:
     - SWAP: intercambiar dos slots del mismo teacher
     - MOVE: mover un slot a un hueco libre
     - SHIFT: mover slot a día distinto
  2. Calcular ΔPenalty = penalty(nuevo) - penalty(actual)
  3. Si ΔPenalty < 0: aceptar siempre (mejora)
  4. Si ΔPenalty ≥ 0: aceptar con probabilidad e^(-ΔPenalty/T)
  5. Decrementar T *= alpha cada iteración
  6. Slots locked = true nunca se mueven

Función de penalización (11 criterios)

Implementada en algorithms/penaltyCalculator.ts. Cada criterio retorna un valor numérico multiplicado por su peso:

penalty = Σ (penaltyCategory_i × weight_i)

Categorías:
  consecutiveHours  → Σ teacher: max(0, bloques_consecutivos - maxConsecutiveHours)
  gaps              → Σ teacher/día: periodos_libres_entre_clases
  preferences       → Σ slot: -preferredHours[day][period] (invertido)
  studentGaps       → Σ group/día: periodos_libres_entre_clases
  doublePeriods     → -Σ subject: bloques_dobles (bonificación → negativa)
  dailyHours        → Σ group/subject/día: max(0, sesiones - maxDailyLessons)
  homeRoom          → Σ slot: 1 si aula ≠ aula_base_del_grupo
  activeDays        → Σ teacher: |días_activos - target_días_activos|
  spacing           → Σ subject/group: penaliza días consecutivos con la misma asignatura
  roomStability     → Σ subject/group: número de aulas distintas usadas
  minRest           → Σ teacher/día: max(0, horas_descanso_requeridas - horas_descanso_reales)

Detección de colisiones

algorithms/constraintEngine.ts evalúa si un slot candidato es válido comprobando:

Para cada slot candidato (lesson, day, hour, weekCycle):
  1. Teacher no tiene otro slot en (day, hour) compatible con weekCycle
  2. ClassGroup no tiene otro slot en (day, hour) compatible con weekCycle
  3. Room no tiene otro slot en (day, hour) compatible con weekCycle
  4. hour ≤ periodsPerDay del TimeFrame del grupo
  5. No es periodo de recreo del TimeFrame

Compatibilidad de weekCycle:
  EVERY_WEEK vs EVERY_WEEK → colisión
  EVERY_WEEK vs WEEK_A/B   → colisión (EVERY ocupa ambas semanas)
  WEEK_A vs WEEK_B         → NO colisión (semanas distintas)

Plataforma de producción

TimeSchool está optimizado para despliegue en Vercel (Next.js nativo) o Railway (Docker). El Dockerfile en la raíz produce una imagen Alpine con el servidor Next.js en modo standalone.

Scripts de npm disponibles

npm run dev       # Servidor de desarrollo (puerto 3000)
npm run build     # prisma generate && next build
npm run start     # Servidor de producción
npm run db:push   # Sincronizar schema (⚠ dev only)
npm run db:migrate# Crear migración Prisma
npm run db:studio # Interfaz visual Prisma Studio
npm run seed      # Datos de demo (IES Villa de Aspe)
npm run test      # Tests unitarios con Vitest
npm run test:coverage # Cobertura de tests

Build de producción

# En Vercel: automático en cada push a main
# En Railway / servidor propio:
docker build -t timeschool .
docker run -p 3000:3000 \
  -e DATABASE_URL=... \
  -e NEXT_PUBLIC_SUPABASE_URL=... \
  # ... resto de variables ...
  timeschool

Checklist de puesta en marcha