Projet Niveau 4 — Web services + dashboard Next.js

⏱️ TL;DR — Vous ouvrez Moodle vers l’extérieur. Vous activez les web services, exposez une fonction externe custom (dans un plugin local), gérez l’authentification par token, puis vous construisez un dashboard Next.js qui lit les données de Moodle (cours, inscriptions, notes) et les affiche dans une UI moderne. Objectif : maîtriser l’API externe de Moodle et faire jouer votre double compétence — le pont Moodle ↔ Next.js, exactement ce qui se facture cher (Partie 13).

🎯 Niveau & objectifs

Niveau : 4 (expert). Prérequis : Niveau 2 (écrire un plugin local) ; maîtrise Next.js App Router.
Durée indicative : 12–18 h.
Vous allez pratiquer : sous-système Web Services, classes/external/ (external functions, définition des paramètres/retours), db/services.php, tokens, protocoles (REST), external_api, consommation depuis un client Next.js, CORS/sécurité d’intégration.

📋 Cahier des charges

Contexte — Une organisation veut un tableau de bord externe (hors Moodle) pour ses responsables : suivre en un écran les cours, le nombre d’inscrits et la progression, avec le look de leurs outils internes. Moodle reste la source de vérité.

Objectif — Exposer proprement les données via web services + un front Next.js qui les consomme de façon sécurisée.

Périmètre inclus

Activation des web services : protocole REST, service externe dédié, utilisateur de service + token.
Utilisation d’au moins une fonction du cœur (ex. core_course_get_courses, core_enrol_get_enrolled_users).
Une fonction externe custom dans un plugin local (local_dashboard_get_stats) : classes/external/get_stats.php avec execute_parameters, execute, execute_returns, déclarée dans db/services.php et db/access.php.
Sécurité : la fonction vérifie le contexte et les capabilities, valide les paramètres (external_value), ne renvoie que le permis.
Un dashboard Next.js 15 (App Router) qui appelle l’endpoint web service et affiche : liste de cours, inscrits par cours, un indicateur de progression.
Le token et l’URL Moodle en variables d’environnement, appels côté serveur (jamais le token dans le navigateur).
Gestion d’erreurs (Moodle indisponible, token invalide) et états de chargement.

Périmètre exclu — Pas de LTI (Niveau 5 : c’est un mécanisme différent, avec launch et grade passback), pas d’écriture massive dans Moodle, pas d’authentification des utilisateurs finaux du dashboard.

Contraintes

La fonction externe custom valide ses entrées et contrôle les capabilities (jamais de fuite de données d’autres contextes).
Le token n’apparaît jamais côté client : tous les appels Moodle passent par le serveur Next.js (route handler / server component).
Documenter le contrat de local_dashboard_get_stats (params, retour).

Livrables

Le plugin local_dashboard (fonction externe + services + access).
Le dépôt Next.js du dashboard.
Un README d’archi : flux d’auth (token), endpoints utilisés, sécurité.

✅ Critères de réussite

Le service REST est activé et testable via la page de documentation API de Moodle avec un token.
local_dashboard_get_stats apparaît dans les fonctions disponibles et renvoie un JSON valide.
La fonction refuse un appel sans la capability requise / hors contexte autorisé.
Le dashboard Next.js affiche cours + inscrits + progression, en lisant Moodle.
Le token n’est jamais exposé au navigateur (vérifiable dans l’onglet réseau).
Le front dégrade proprement si Moodle est indisponible.

🗺️ Endroits à visiter

Endroit	Où	Pourquoi y aller
Vue d’ensemble des web services	Admin → Serveur → Web services → Vue d’ensemble	L’assistant pas-à-pas officiel d’activation
Gérer les protocoles	Admin → Serveur → Web services → Protocoles	Activer REST
Services externes	Admin → Serveur → Web services → Services externes	Créer un service et y ajouter des fonctions
Gérer les tokens	Admin → Serveur → Web services → Gérer les tokens	Créer le token de l’utilisateur de service
Documentation de l’API	Admin → Serveur → Web services → API Documentation	La liste des fonctions + leur signature, testable
Code du cœur : `lib/externallib.php`	filesystem	`external_api`, `external_function_parameters`, `external_value`
Code du cœur : `course/externallib.php`	filesystem	Un modèle réel de fonction externe à imiter
`db/services.php` d’un plugin	filesystem	La déclaration qui expose votre fonction

💡 Pour un dev React — Une external function Moodle, c’est un endpoint typé : execute_parameters() et execute_returns() sont un schéma (pensez zod / OpenAPI) que Moodle valide pour vous à l’entrée et à la sortie. Une fois le token obtenu, appeler Moodle depuis Next.js est un simple fetch — toute votre expertise front s’applique. La règle d’or : le token vit côté serveur (route handler / server action), jamais dans le bundle client. C’est votre pont Moodle↔moderne, la compétence rare de la Partie 13.

⚠️ Piège — Une fonction externe qui oublie de valider le contexte et les capabilities est une faille : les web services court-circuitent l’UI mais pas le modèle de permissions. Reproduisez toujours, dans execute(), les vérifications require_capability / validate_context que ferait une page normale.

🚀 Étapes suggérées

Activer les web services (assistant), protocole REST, service + token.
Tester une fonction du cœur via la page de documentation API.
Créer local_dashboard ; classes/external/get_stats.php (params/exec/returns).
Déclarer dans db/services.php + capability dans db/access.php ; l’ajouter au service.
Tester local_dashboard_get_stats avec le token.
Monter le dashboard Next.js : route serveur qui appelle Moodle avec le token.
UI : cours, inscrits, progression ; gestion d’erreurs.
Documenter le contrat et le flux d’auth.

🎁 Bonus

Ajoutez la pagination et un filtre par catégorie à get_stats.
Mettez en cache côté Next.js (revalidation) les données peu changeantes.
Ajoutez un graphe de progression (le token restant côté serveur).

🔗 Chapitres du cours liés

Projet suivant : Niveau 5 — QuizLab, outil LTI externe.