Consumo del panel del estudiante — get_student_panel

Contrato de integración para el desarrollador del servicio de IA externo. El servicio "Componente IA Externo" expone la función local_pccntr8203403_dashboard_get_student_panel, que en una sola llamada devuelve el mismo panel de progreso que el estudiante ve en la modal "Ver mi avance": avance general, desempeño, actividades pendientes, racha, avance por módulos, últimas calificaciones y alertas académicas, calculado con la misma lógica que usa la plataforma. No hace falta combinar funciones core para reconstruir estas métricas.

Ficha técnica del componente que la implementa: local_pccntr8203403_dashboard.

Requisitos de acceso

Requisito	Detalle
Token	Del servicio "Componente IA Externo" — ver Web Services IA
Capacidad	local/pccntr8203403_dashboard:viewstudentpanel en el contexto del curso
Capacidad	moodle/course:view en los cursos consultados
Matrícula	La cuenta de servicio necesita un rol dentro de los cursos que va a consultar

La capacidad viewstudentpanel se define sin arquetipos: no la hereda ningún rol estándar y hay que asignarla explícitamente al rol de la cuenta de servicio.

Cómo pedir los datos

curl -X POST "https://<host-del-campus>/webservice/rest/server.php" \
  -d "wstoken=<TOKEN>" \
  -d "wsfunction=local_pccntr8203403_dashboard_get_student_panel" \
  -d "moodlewsrestformat=json" \
  -d "userid=<ID_ESTUDIANTE>" \
  -d "courseid=<ID_CURSO>"

Parámetro	Valor
userid	Id Moodle del estudiante — el mismo moodle_user_id que llega en el payload del tutor (/webhook/v1/campus/tutor)
courseid	Opcional. Id del curso. Con 0 (u omitido) responde todos los cursos activos del estudiante

Respuesta (abreviada)

{
  "userid": 1234,
  "firstname": "Nombre",
  "fullname": "Nombre Apellido",
  "generatedat": 1784679108,           // unix timestamp de generación
  "courses": [{
    "courseid": 2,
    "coursename": "Nombre del curso",
    "progress": { "available": true, "pct": 5, "completed": 2, "total": 40,
                  "courseavgpct": 5.7, "state": "atencion" },
    "grade":    { "value5": null, "courseavg5": null, "state": null },   // escala 0–5
    "pending":  { "count": 38, "state": "bien" },
    "streak":   { "days": 0, "courseavg": 0, "state": "bien" },          // días consecutivos
    "modules": [
      { "name": "STS Lenguaje", "sectionnum": 1, "pct": 0,
        "complete": false, "completed": 0, "total": 8 }
    ],
    "recentgrades": [
      { "name": "Quiz final M1", "grade5": 4.2, "date": 1784500000 }     // máx. 3, recientes primero
    ],
    "alerts": [
      { "code": "inactivity", "level": "critico", "motivational": false }
    ]
  }]
}

Diccionario rápido

• state: posición del estudiante frente al promedio de su curso: excelente | bien | atencion | riesgo. null = no calculable.
• null en cualquier valor = sin datos aún (p. ej. sin calificaciones, o curso sin seguimiento de finalización → progress.available: false).
• alerts: Moodle entrega solo el código y el nivel (leve | critico); la redacción del mensaje al estudiante la define el agente. motivational: true = alerta positiva (felicitar, no advertir).

Código de alerta	Significa
progress_delay	Retraso frente al cronograma del curso
inactivity	Días sin ingresar al curso
low_performance	Promedio bajo (escala 0–5)
performance_drop	Últimas notas en descenso
irregular_pace	Ingresa pero no avanza
modules_behind	Módulos que ya debería tener completos
dropout_risk	Riesgo de abandono (indicador compuesto)
low_participation	Sin participación en foros/comentarios
pending_eval	Evaluaciones (quizzes) sin intentar
positive_streak	Racha positiva — motivacional
high_performance	Sobre el promedio del curso — motivacional
due_soon	Entrega próxima a vencer. No dispara por Web Service: la API de calendario de Moodle está ligada al usuario de la sesión, que en este flujo es la cuenta de servicio y no el estudiante consultado

Notas y errores comunes

• Modelo pull: consultar bajo demanda o periódicamente. Sugerido: no más de una consulta por estudiante/curso cada pocos minutos (los promedios de curso ya van cacheados en la plataforma).
• La racha vía API solo cuenta días con actividad real (en la web "hoy" siempre cuenta porque el estudiante está navegando; aquí no).
• invalidtoken → token vencido o mal copiado.
• required_capability_exception / "Curso o actividad no accesible" → a la cuenta del token le falta local/pccntr8203403_dashboard:viewstudentpanel o moodle/course:view en ese curso, o no está matriculada en él. Ver la tabla de requisitos de acceso más arriba.
• usernotenrolled → el userid no está matriculado en ese courseid.