Teacher Role: Managing Subjects and Grading Students

Teachers — referred to as docentes throughout the platform — are the primary content creators in NuestraVoz. They own the in-classroom experience for their assigned subjects: posting announcements, uploading resources, building activities (simple file submissions or auto-graded online forms), and entering the final grade record for each enrolled student. Because the platform is used by a licensed institution, teacher accounts are not immediately active — every self-registration enters a pending state and requires explicit approval by an admin before the teacher can log in.

Registration and Approval Flow

Self-registration

Teachers register using the same /api/auth/register endpoint as students, but with rol: 'docente'. The server detects the role and sets status: 'pendiente' instead of 'activo':

// apps/api/src/routes/auth.ts
const status = rol === 'docente' ? 'pendiente' : 'activo';

The API returns a 201 with a confirmation message. No session cookie is issued — the teacher cannot log in yet.

Pending state behaviour

Attempting to log in while status === 'pendiente' returns:

{ "error": "Tu cuenta de docente está pendiente de aprobación" }

with HTTP 403. This check occurs in /api/auth/login after credential validation and before the session cookie is set.

Admin approval

An admin approves the account by patching the status:

PATCH /api/users/:id
Content-Type: application/json

{ "status": "activo" }

Once approved the teacher can log in normally and their dashboard will show their assigned subjects.

If a teacher registers with the wrong email or information, the admin can update any profile field — including email and password — via the same PATCH /api/users/:id endpoint before or after approval.

Subject Access Model

A docente sees only subjects where their user ID matches the docente_id column of the materias table. This filter is applied in every subject-scoped query. The assertDocenteMateria helper in apps/api/src/lib/finales.ts enforces this for the finals endpoints:

// conceptual logic from assertDocenteMateria
if (rol === 'docente') {
  // only allow access when docente_id === req.user.id
}
if (rol === 'admin' || rol === 'preceptor') {
  // unconditionally allowed
}

A docente who attempts to access another teacher’s subject will receive 403 Sin permisos sobre esta materia.

Dashboard

The teacher dashboard is served by DocenteDashboardPage.tsx, which calls two endpoints in parallel:

Overview statistics

GET /api/dashboard/docente

Returns a DocenteDashboard object:

// packages/shared/src/types.ts
export interface DocenteDashboard {
  entregasPorCalificar: number;  // ungraded submissions across all assigned subjects
  cursosAsignados: number;       // total active subjects with this teacher's docente_id
  totalAlumnos: number;          // total enrolled students across those subjects
  actividadesActivas: number;    // activities with estado = 'activa'
}

The entregasPorCalificar counter is highlighted in red when non-zero, giving the teacher an immediate visual cue of outstanding grading work.

Pending grading queue

GET /api/dashboard/docente/pendientes-calificar

Returns an array of ActividadPendienteCalificar:

// packages/shared/src/types.ts
export interface ActividadPendienteCalificar {
  actividad_id: string;
  titulo: string;
  materia_id: string;
  materia_nombre: string;
  pendientes: number;  // count of ungraded submissions for this activity
}

Each item links directly to the activity view inside the relevant virtual classroom (/aula/:materia_id?tab=actividades&ver=:actividad_id).

Classroom Features

Within each assigned subject’s virtual classroom, docentes can perform the following operations:

Announcements

Post info or warning announcements visible to all enrolled students. Validated by createAnuncioSchema (titulo ≥ 2 chars, contenido ≥ 2 chars).

Resources

Upload files as classroom resources. Each resource has a nombre (max 150 chars), an optional descripcion (max 2,000 chars), a storage_path, and a tipo tag.

Activities

Create entregable_simple (file upload) or formulario (auto-graded online form) activities with an optional fecha_entrega deadline and a permite_entrega_tardia flag.

Forum

Create threads in the subject forum with a title, body, and optional tags array. Reply to existing threads or nested posts.

Creating an activity

POST /api/aula/:materiaId/actividades
Content-Type: application/json

{
  "titulo": "Práctica de lectura en voz alta",
  "descripcion": "Grabá un minuto de lectura y adjuntá el audio.",
  "fecha_entrega": "2025-08-15T23:59:00Z",
  "tipo": "entregable_simple",
  "permite_entrega_tardia": true
}

For tipo: 'formulario', the body must include a preguntas array where each question has an enunciado, a puntos value, and at least two opciones. The total points across all questions must sum to exactly 10:

{
  "titulo": "Cuestionario fonética básica",
  "tipo": "formulario",
  "preguntas": [
    {
      "enunciado": "¿Cuál es el punto de articulación de la /p/?",
      "multiple": false,
      "puntos": 5,
      "opciones": [
        { "texto": "Bilabial",    "es_correcta": true  },
        { "texto": "Labiodental", "es_correcta": false },
        { "texto": "Alveolar",    "es_correcta": false }
      ]
    },
    {
      "enunciado": "¿Qué vocales son posteriores?",
      "multiple": true,
      "puntos": 5,
      "opciones": [
        { "texto": "a", "es_correcta": false },
        { "texto": "o", "es_correcta": true  },
        { "texto": "u", "es_correcta": true  }
      ]
    }
  ]
}

Grading a file submission

PATCH /api/aula/:materiaId/actividades/:actividadId/entregas/:entregaId/calificar
Content-Type: application/json

{ "nota": 8 }

nota must be between 1 and 10 (inclusive). Once graded, the submission estado changes to 'calificada' and the student can see their mark in their activity list.

Managing activity state

PATCH /api/aula/:materiaId/actividades/:actividadId/estado
Content-Type: application/json

{ "estado": "cerrada" }

Valid states are 'activa', 'cerrada', and 'terminada'. Students cannot submit to a closed or finished activity even when permite_entrega_tardia is true.

Final Grade Entry

At the end of the academic term, docentes enter official final marks via:

GET /api/finales/materia/:materiaId

This returns a FinalesMateriaResponse with the academic year and the full enrolment list:

// packages/shared/src/types.ts
export interface FinalesMateriaResponse {
  anio_academico: number;
  alumnos: AlumnoNotaFinal[];
}

export interface AlumnoNotaFinal {
  estudiante_id: string;
  nombre: string;
  apellido: string;
  email: string;
  dni: string | null;
  nota: number | null;              // final exam mark (1–10)
  nota_recuperatorio: number | null; // resit mark (1–10)
  libre: boolean;                   // true if student sat as libre
  regular: boolean;                 // true if student is regular
}

To save grades, send a bulk upsert:

PUT /api/finales/materia/:materiaId
Content-Type: application/json

{
  "notas": [
    {
      "estudiante_id": "uuid-alumno-1",
      "nota": 7,
      "nota_recuperatorio": null,
      "libre": false,
      "regular": true
    },
    {
      "estudiante_id": "uuid-alumno-2",
      "nota": null,
      "nota_recuperatorio": 6,
      "libre": false,
      "regular": true
    }
  ]
}

libre and regular cannot both be true for the same student — the server rejects the request with 400 Libre y Regular no pueden estar marcados a la vez. A student who is libre cannot be simultaneously regular.

The server uses an upsert on (estudiante_id, materia_id, anio_academico) so repeated saves are idempotent — submitting the same data twice does not create duplicate rows.

What Docentes Cannot Do

Create, edit, or delete user accounts
Create or delete careers or subjects
Access another teacher’s virtual classroom
Manage student enrolments (inscripciones)
View platform-wide dashboard statistics or the audit log
Download other students’ bulletins (only accessible to admin and preceptor)

Getting Started

Core Features

User Roles

Configuration & Deployment

Registration and Approval Flow

Self-registration

Pending state behaviour

Admin approval

Subject Access Model

Dashboard

Overview statistics

Pending grading queue

Classroom Features

Announcements

Resources

Activities

Forum

Creating an activity

Grading a file submission

Managing activity state

Final Grade Entry

What Docentes Cannot Do

Build docs developers (and LLMs) love

Getting Started

Core Features

User Roles

Configuration & Deployment

Documentation Index

​Registration and Approval Flow

​Self-registration

​Pending state behaviour

​Admin approval

​Subject Access Model

​Dashboard

​Overview statistics

​Pending grading queue

​Classroom Features

Announcements

Resources

Activities

Forum

​Creating an activity

​Grading a file submission

​Managing activity state

​Final Grade Entry

​What Docentes Cannot Do

Build docs developers (and LLMs) love

Registration and Approval Flow

Self-registration

Pending state behaviour

Admin approval

Subject Access Model

Dashboard

Overview statistics

Pending grading queue

Classroom Features

Creating an activity

Grading a file submission

Managing activity state

Final Grade Entry

What Docentes Cannot Do