Saltar al contenido principal

ADR-001: Capa de funciones externas para exponer datos del dashboard al agente IA

Estado: Aceptado | Fecha: 2026-06-09 | Autores: jcarroyos@gmail.com

Contexto​

El plugin local_pccntr8203403_dashboard contiene toda la logica de negocio necesaria para el Scope 3 del proyecto (acceso de un agente IA externo al contexto academico del estudiante). Las clases course_stats, student_stats y academic_alerts estan implementadas, estables y con datos reales en produccion.

Sin embargo, el plugin no tiene capa de Web Services. Verificacion al 2026-06-09:

  • No existe db/services.php — ninguna funcion externa registrada.
  • No existe classes/external/ — ninguna clase que extienda core_external\external_api.
  • En /admin/settings.php?section=externalservices no hay nada que agregar porque Moodle solo lista funciones ya declaradas.

Como resultado, los datos de alertas, progreso y calificaciones son internamente accesibles para el tema y el bloque, pero no consultables desde fuera de Moodle (ni via REST, ni via SOAP, ni via token).

Lo que ya esta listo​

La estructura de retorno de las funciones principales ya es limpia y serializable sin cambios:

// academic_alerts::get_active_alerts()
['code' => string, 'level' => 'leve'|'critico', 'motivational' => bool]

// course_stats::get_user_progress()
['completed' => int, 'total' => int, 'percentage' => float]

// course_stats::get_user_module_progress()
['name' => string, 'pct' => int, 'complete' => bool, 'activities' => string]

Todos los metodos relevantes son public static sin dependencias de sesion de usuario web, lo que facilita su uso desde una funcion externa.

Decision​

Implementar una capa de funciones externas Moodle dentro de local_pccntr8203403_dashboard (sin crear un plugin separado) que envuelva los datos del dashboard y los exponga via REST con autenticacion por token y verificacion de capacidades.

Se elige extender el plugin existente (no crear local_pccntr8203403_api) para mantener la cohesion: la logica de datos y su exposicion externa viven en el mismo componente.

Lo que hay que construir​

db/services.php​

Registrar la funcion externa principal:

$functions = [
    'local_pccntr8203403_dashboard_get_learner_context' => [
        'classname'   => 'local_pccntr8203403_dashboard\external\get_learner_context',
        'methodname'  => 'execute',
        'description' => 'Returns full learner context for a course: progress, grades, alerts.',
        'type'        => 'read',
        'capabilities'=> 'local/pccntr8203403_dashboard:viewlearnercontext',
        'ajax'        => false,
        'services'    => [],
    ],
];

db/access.php​

Capacidad que el token debe tener para llamar a la funcion:

$capabilities = [
    'local/pccntr8203403_dashboard:viewlearnercontext' => [
        'riskbitmask' => RISK_PERSONAL,
        'captype'     => 'read',
        'contextlevel'=> CONTEXT_COURSE,
        'archetypes'  => ['manager' => CAP_ALLOW],
    ],
];

classes/external/get_learner_context.php​

Clase que extiende core_external\external_api:

  • execute_parameters() — acepta courseid (int) y userid (int).
  • execute($courseid, $userid) — llama a course_stats, student_stats y academic_alerts, valida capacidad, retorna estructura serializada.
  • execute_returns() — define la estructura de retorno con external_single_structure y external_multiple_structure.

db/upgrade.php​

Bump de version del plugin para que Moodle registre las nuevas capacidades.

Referencias​