@programisto/edrm-exams 0.3.8 → 0.3.10

package/dist/modules/edrm-exams/routes/exams.router.js

@@ -84,7 +84,31 @@ class ExamsRouter extends EnduranceRouter {
             requireAuth: false,
             permissions: []
         };
-        // Créer une catégorie
+        /**
+         * @swagger
+         * /exams/categories:
+         *   post:
+         *     summary: Créer une catégorie
+         *     description: Crée une catégorie de test avec son nom.
+         *     tags: [Examens]
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             required: [name]
+         *             properties:
+         *               name:
+         *                 type: string
+         *     responses:
+         *       201:
+         *         description: Catégorie créée
+         *       400:
+         *         description: Paramètres manquants
+         *       500:
+         *         description: Erreur interne
+         */
         this.post('/categories', authenticatedOptions, async (req, res) => {
             const { name } = req.body;
             if (!name) {
@@ -100,7 +124,19 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Lister toutes les catégories
+        /**
+         * @swagger
+         * /exams/categories:
+         *   get:
+         *     summary: Lister les catégories
+         *     description: Retourne toutes les catégories de test.
+         *     tags: [Examens]
+         *     responses:
+         *       200:
+         *         description: Liste des catégories
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/categories', authenticatedOptions, async (req, res) => {
             try {
                 const categories = await TestCategory.find();
@@ -111,7 +147,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Obtenir une catégorie par son ID
+        /**
+         * @swagger
+         * /exams/categorie/{id}:
+         *   get:
+         *     summary: Détail d'une catégorie
+         *     description: Récupère une catégorie par son identifiant.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Catégorie trouvée
+         *       404:
+         *         description: Catégorie non trouvée
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/categorie/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             try {
@@ -126,7 +182,31 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Créer un job type
+        /**
+         * @swagger
+         * /exams/jobs:
+         *   post:
+         *     summary: Créer un job cible
+         *     description: Crée un job cible pour les tests.
+         *     tags: [Examens]
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             required: [name]
+         *             properties:
+         *               name:
+         *                 type: string
+         *     responses:
+         *       201:
+         *         description: Job créé
+         *       400:
+         *         description: Paramètres manquants
+         *       500:
+         *         description: Erreur interne
+         */
         this.post('/jobs', authenticatedOptions, async (req, res) => {
             const { name } = req.body;
             if (!name) {
@@ -142,7 +222,19 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Lister tous les jobs
+        /**
+         * @swagger
+         * /exams/jobs:
+         *   get:
+         *     summary: Lister les jobs cibles
+         *     description: Retourne l'ensemble des jobs disponibles pour les tests.
+         *     tags: [Examens]
+         *     responses:
+         *       200:
+         *         description: Liste des jobs
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/jobs', authenticatedOptions, async (req, res) => {
             try {
                 const jobs = await TestJob.find();
@@ -153,7 +245,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Obtenir un job par son ID
+        /**
+         * @swagger
+         * /exams/jobs/{id}:
+         *   get:
+         *     summary: Détail d'un job
+         *     description: Récupère un job cible par ID.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Job trouvé
+         *       404:
+         *         description: Job non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/jobs/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             try {
@@ -168,7 +280,19 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Migrer tous les tests avec l'ancien format targetJob
+        /**
+         * @swagger
+         * /exams/migrate-targetjobs:
+         *   post:
+         *     summary: Migrer les tests (targetJob)
+         *     description: Convertit les tests utilisant l'ancien format de targetJob vers les références TestJob.
+         *     tags: [Examens]
+         *     responses:
+         *       200:
+         *         description: Migration exécutée
+         *       500:
+         *         description: Erreur interne
+         */
         this.post('/migrate-targetjobs', authenticatedOptions, async (req, res) => {
             try {
                 const tests = await Test.find();
@@ -198,7 +322,48 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Erreur interne du serveur' });
             }
         });
-        // Créer un test
+        /**
+         * @swagger
+         * /exams/test:
+         *   post:
+         *     summary: Créer un test
+         *     description: Crée un test avec titre, description, job cible, séniorité et catégories.
+         *     tags: [Examens]
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             required: [title, targetJob, seniorityLevel]
+         *             properties:
+         *               title:
+         *                 type: string
+         *               description:
+         *                 type: string
+         *               targetJob:
+         *                 type: string
+         *               seniorityLevel:
+         *                 type: string
+         *               categories:
+         *                 type: array
+         *                 items:
+         *                   type: object
+         *                   properties:
+         *                     name:
+         *                       type: string
+         *                     expertiseLevel:
+         *                       type: string
+         *               state:
+         *                 type: string
+         *     responses:
+         *       201:
+         *         description: Test créé
+         *       400:
+         *         description: Paramètres manquants
+         *       500:
+         *         description: Erreur interne
+         */
         this.post('/test', authenticatedOptions, async (req, res) => {
             const { title, description, targetJob, seniorityLevel, categories, state = 'draft' } = req.body;
             const user = req.user;
@@ -239,7 +404,8 @@ class ExamsRouter extends EnduranceRouter {
                     targetJob: targetJobId,
                     seniorityLevel,
                     state,
-                    categories: processedCategories
+                    categories: processedCategories,
+                    ...(req.entity?._id && { entityId: req.entity._id })
                 });
                 await newTest.save();
                 res.status(201).json({ message: 'test created with sucess', data: newTest });
@@ -249,7 +415,35 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Modifier un test
+        /**
+         * @swagger
+         * /exams/test/{id}:
+         *   put:
+         *     summary: Modifier un test
+         *     description: Met à jour les métadonnées, catégories ou questions d'un test.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *     responses:
+         *       200:
+         *         description: Test modifié
+         *       404:
+         *         description: Test non trouvé
+         *       400:
+         *         description: Données invalides
+         *       500:
+         *         description: Erreur interne
+         */
         this.put('/test/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             const { title, description, targetJob, seniorityLevel, categories, state, questions } = req.body;
@@ -258,6 +452,9 @@ class ExamsRouter extends EnduranceRouter {
                 if (!test) {
                     return res.status(404).json({ message: 'Test non trouvé' });
                 }
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'Test non trouvé' });
+                }
                 if (title)
                     test.title = title;
                 if (description)
@@ -318,7 +515,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Erreur interne du serveur' });
             }
         });
-        // Supprimer un test
+        /**
+         * @swagger
+         * /exams/test/{id}:
+         *   delete:
+         *     summary: Supprimer un test
+         *     description: Supprime un test ainsi que ses questions et résultats associés.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Test supprimé
+         *       404:
+         *         description: Test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.delete('/test/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             try {
@@ -326,6 +543,9 @@ class ExamsRouter extends EnduranceRouter {
                 if (!test) {
                     return res.status(404).json({ message: 'Test not found' });
                 }
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'Test not found' });
+                }
                 for (let i = 0; i < test.questions.length; i++) {
                     await TestQuestion.findByIdAndDelete(test.questions[i].questionId);
                 }
@@ -338,7 +558,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Obtenir un test par son ID
+        /**
+         * @swagger
+         * /exams/test/{id}:
+         *   get:
+         *     summary: Détail d'un test
+         *     description: Retourne un test avec ses questions et nom du job cible.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Test trouvé
+         *       404:
+         *         description: Test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/test/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             try {
@@ -346,6 +586,10 @@ class ExamsRouter extends EnduranceRouter {
                 if (!test) {
                     return res.status(404).json({ message: 'no test founded with this id' });
                 }
+                // Vérifier que le test appartient à l'entité courante (multi-entités)
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'no test founded with this id' });
+                }
                 // Migration automatique si nécessaire
                 await migrateTestIfNeeded(test);
                 const questions = [];
@@ -367,7 +611,59 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Lister tous les tests
+        /**
+         * @swagger
+         * /exams:
+         *   get:
+         *     summary: Lister les tests
+         *     description: Liste paginée des tests avec filtres, recherche et tri.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: query
+         *         name: page
+         *         schema:
+         *           type: integer
+         *           default: 1
+         *       - in: query
+         *         name: limit
+         *         schema:
+         *           type: integer
+         *           default: 10
+         *       - in: query
+         *         name: search
+         *         schema:
+         *           type: string
+         *       - in: query
+         *         name: targetJob
+         *         schema:
+         *           type: string
+         *           default: all
+         *       - in: query
+         *         name: seniorityLevel
+         *         schema:
+         *           type: string
+         *           default: all
+         *       - in: query
+         *         name: state
+         *         schema:
+         *           type: string
+         *           default: all
+         *       - in: query
+         *         name: sortBy
+         *         schema:
+         *           type: string
+         *           default: updatedAt
+         *       - in: query
+         *         name: sortOrder
+         *         schema:
+         *           type: string
+         *           default: desc
+         *     responses:
+         *       200:
+         *         description: Tests paginés
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/', authenticatedOptions, async (req, res) => {
             try {
                 const page = parseInt(req.query.page) || 1;
@@ -381,6 +677,10 @@ class ExamsRouter extends EnduranceRouter {
                 const sortOrder = req.query.sortOrder || 'desc';
                 // Construction de la requête de recherche
                 const query = {};
+                // Filtre par entité (contexte multi-entités)
+                if (req.entity?._id) {
+                    query.entityId = req.entity._id;
+                }
                 // Filtres
                 if (targetJob !== 'all') {
                     // Si on filtre par targetJob, on cherche d'abord le TestJob correspondant
@@ -462,7 +762,36 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Supprimer une catégorie d'un test
+        /**
+         * @swagger
+         * /exams/test/removeCategory/{testId}:
+         *   delete:
+         *     summary: Retirer une catégorie d'un test
+         *     description: Supprime une catégorie d'un test par son nom.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: testId
+         *         required: true
+         *         schema:
+         *           type: string
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             properties:
+         *               categoryName:
+         *                 type: string
+         *     responses:
+         *       200:
+         *         description: Catégorie supprimée
+         *       404:
+         *         description: Test ou catégorie non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.delete('/test/removeCategory/:testId', authenticatedOptions, async (req, res) => {
             const { testId } = req.params;
             const { categoryName } = req.body;
@@ -470,9 +799,13 @@ class ExamsRouter extends EnduranceRouter {
                 const category = await TestCategory.findOne({ name: categoryName });
                 if (!category)
                     return res.status(404).json({ message: 'Category not found' });
-                const test = await Test.findByIdAndUpdate(testId, { $pull: { categories: { categoryId: category._id } } }, { new: true });
+                let test = await Test.findById(testId);
                 if (!test)
                     return res.status(404).json({ message: 'Test not found' });
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'Test not found' });
+                }
+                test = await Test.findByIdAndUpdate(testId, { $pull: { categories: { categoryId: category._id } } }, { new: true });
                 res.status(200).json({ message: 'Category removed', test });
             }
             catch (err) {
@@ -480,7 +813,38 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Ajouter une catégorie à un test
+        /**
+         * @swagger
+         * /exams/test/addCategory/{testId}:
+         *   put:
+         *     summary: Ajouter une catégorie à un test
+         *     description: Ajoute une catégorie (créée si besoin) à un test avec niveau d'expertise.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: testId
+         *         required: true
+         *         schema:
+         *           type: string
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             properties:
+         *               categoryName:
+         *                 type: string
+         *               expertiseLevel:
+         *                 type: string
+         *     responses:
+         *       200:
+         *         description: Catégorie ajoutée
+         *       404:
+         *         description: Test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.put('/test/addCategory/:testId', authenticatedOptions, async (req, res) => {
             const { testId } = req.params;
             const { categoryName, expertiseLevel } = req.body;
@@ -494,6 +858,9 @@ class ExamsRouter extends EnduranceRouter {
                 if (!test) {
                     return res.status(404).json({ message: 'Test not found' });
                 }
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'Test not found' });
+                }
                 const categoryExists = test.categories.some(cat => cat.categoryId.equals(category._id));
                 if (categoryExists) {
                     return res.status(200).json({ message: 'Category already exists in the test' });
@@ -507,7 +874,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Obtenir une question par son ID
+        /**
+         * @swagger
+         * /exams/test/question/{questionId}:
+         *   get:
+         *     summary: Détail d'une question
+         *     description: Retourne une question de test par son identifiant.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: questionId
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Question trouvée
+         *       404:
+         *         description: Question non trouvée
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/test/question/:questionId', authenticatedOptions, async (req, res) => {
             const { questionId } = req.params;
             const question = await TestQuestion.findById(questionId);
@@ -516,7 +903,27 @@ class ExamsRouter extends EnduranceRouter {
             }
             res.status(200).json({ data: question });
         });
-        // Obtenir toutes les questions d'un test
+        /**
+         * @swagger
+         * /exams/test/questions/{testId}:
+         *   get:
+         *     summary: Lister les questions d'un test
+         *     description: Retourne toutes les questions d'un test.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: testId
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Questions retournées
+         *       404:
+         *         description: Test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/test/questions/:testId', authenticatedOptions, async (req, res) => {
             const { testId } = req.params;
             try {
@@ -524,6 +931,9 @@ class ExamsRouter extends EnduranceRouter {
                 if (!test) {
                     return res.status(404).json({ message: 'Test not found' });
                 }
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'Test not found' });
+                }
                 const questions = [];
                 for (const questionId of test.questions) {
                     const question = await TestQuestion.findById(questionId);
@@ -538,7 +948,32 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Supprimer une question d'un test
+        /**
+         * @swagger
+         * /exams/test/question/{testId}/{questionId}:
+         *   delete:
+         *     summary: Supprimer une question d'un test
+         *     description: Supprime une question spécifique et réordonne les questions restantes.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: testId
+         *         required: true
+         *         schema:
+         *           type: string
+         *       - in: path
+         *         name: questionId
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Question supprimée
+         *       404:
+         *         description: Test ou question non trouvés
+         *       500:
+         *         description: Erreur interne
+         */
         this.delete('/test/question/:testId/:questionId', authenticatedOptions, async (req, res) => {
             const { testId, questionId } = req.params;
             const question = await TestQuestion.findByIdAndDelete(questionId);
@@ -549,6 +984,9 @@ class ExamsRouter extends EnduranceRouter {
             if (!test) {
                 return res.status(404).json({ message: 'no test founded with this id' });
             }
+            if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                return res.status(404).json({ message: 'no test founded with this id' });
+            }
             // Supprimer la question du tableau questions en filtrant par questionId
             test.questions = test.questions.filter(q => q.questionId.toString() !== questionId);
             // Recalculer les ordres pour que ça se suive
@@ -558,13 +996,36 @@ class ExamsRouter extends EnduranceRouter {
             await test.save();
             res.status(200).json({ message: 'question deleted with sucess' });
         });
-        // Supprimer toutes les questions d'un test
+        /**
+         * @swagger
+         * /exams/test/questions/{testId}:
+         *   delete:
+         *     summary: Supprimer toutes les questions d'un test
+         *     description: Supprime toutes les questions associées à un test.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: testId
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Questions supprimées
+         *       404:
+         *         description: Test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.delete('/test/questions/:testId', authenticatedOptions, async (req, res) => {
             const { testId } = req.params;
             const test = await Test.findById(testId);
             if (!test) {
                 return res.status(404).json({ message: 'no test founded with this id' });
             }
+            if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                return res.status(404).json({ message: 'no test founded with this id' });
+            }
             for (const questionId of test.questions) {
                 await TestQuestion.findByIdAndDelete(questionId);
             }
@@ -572,7 +1033,33 @@ class ExamsRouter extends EnduranceRouter {
             await test.save();
             res.status(200).json({ message: 'questions deleted with sucess' });
         });
-        // Modifier une question
+        /**
+         * @swagger
+         * /exams/test/modifyQuestion/{id}:
+         *   put:
+         *     summary: Modifier une question
+         *     description: Met à jour les champs d'une question (texte, score, temps, réponses possibles).
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *     responses:
+         *       200:
+         *         description: Question modifiée
+         *       404:
+         *         description: Question non trouvée
+         *       500:
+         *         description: Erreur interne
+         */
         this.put('/test/modifyQuestion/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             const { instruction, maxScore, time, possibleResponses, textType } = req.body;
@@ -604,7 +1091,42 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Ajouter une question à un test
+        /**
+         * @swagger
+         * /exams/test/addCustomQuestion/{id}:
+         *   put:
+         *     summary: Ajouter une question personnalisée
+         *     description: Ajoute une question manuelle à un test.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             properties:
+         *               questionType:
+         *                 type: string
+         *               instruction:
+         *                 type: string
+         *               maxScore:
+         *                 type: number
+         *               time:
+         *                 type: number
+         *     responses:
+         *       200:
+         *         description: Question ajoutée
+         *       404:
+         *         description: Test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.put('/test/addCustomQuestion/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             const { questionType, instruction, maxScore, time } = req.body;
@@ -613,6 +1135,9 @@ class ExamsRouter extends EnduranceRouter {
                 if (!test) {
                     return res.status(404).json({ message: 'no test founded with this id' });
                 }
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'no test founded with this id' });
+                }
                 const question = new TestQuestion({
                     questionType,
                     instruction,
@@ -629,7 +1154,40 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Ajouter une question à un test
+        /**
+         * @swagger
+         * /exams/test/addQuestion/{id}:
+         *   put:
+         *     summary: Générer et ajouter une question
+         *     description: Génère une question via assistant et l'ajoute au test.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             properties:
+         *               questionType:
+         *                 type: string
+         *               category:
+         *                 type: string
+         *               expertiseLevel:
+         *                 type: string
+         *     responses:
+         *       200:
+         *         description: Question générée et ajoutée
+         *       404:
+         *         description: Test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.put('/test/addQuestion/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             const { questionType, category, expertiseLevel } = req.body;
@@ -638,6 +1196,9 @@ class ExamsRouter extends EnduranceRouter {
                 if (!test) {
                     return res.status(404).json({ message: 'no test founded with this id' });
                 }
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'no test founded with this id' });
+                }
                 const otherQuestionsIds = test.questions.map(question => question.questionId);
                 const otherQuestions = await TestQuestion.find({ _id: { $in: otherQuestionsIds } });
                 const jobName = await getJobName(test.targetJob);
@@ -660,7 +1221,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Mélanger les questions d'un test
+        /**
+         * @swagger
+         * /exams/test/shuffle/{testId}:
+         *   get:
+         *     summary: Mélanger les questions d'un test
+         *     description: Mélange l'ordre des questions d'un test.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: testId
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Questions mélangées
+         *       404:
+         *         description: Test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/test/shuffle/:testId', authenticatedOptions, async (req, res) => {
             const { testId } = req.params;
             try {
@@ -668,6 +1249,9 @@ class ExamsRouter extends EnduranceRouter {
                 if (!test) {
                     return res.status(404).json({ message: 'Test not found' });
                 }
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'Test not found' });
+                }
                 for (let i = test.questions.length - 1; i > 0; i--) {
                     const j = Math.floor(Math.random() * (i + 1));
                     [test.questions[i], test.questions[j]] = [test.questions[j], test.questions[i]];
@@ -680,7 +1264,36 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Ajouter un texte d'invitation à un test
+        /**
+         * @swagger
+         * /exams/test/addInvitationText/{id}:
+         *   put:
+         *     summary: Ajouter un texte d'invitation
+         *     description: Ajoute ou met à jour le texte d'invitation utilisé pour un test.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             properties:
+         *               invitationText:
+         *                 type: string
+         *     responses:
+         *       200:
+         *         description: Texte mis à jour
+         *       404:
+         *         description: Test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.put('/test/addInvitationText/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             const { invitationText } = req.body;
@@ -689,6 +1302,9 @@ class ExamsRouter extends EnduranceRouter {
                 if (!test) {
                     return res.status(404).json({ message: 'no test founded with this id' });
                 }
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'no test founded with this id' });
+                }
                 test.invitationText = invitationText;
                 await test.save();
                 res.status(200).json({
@@ -701,7 +1317,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Obtenir un résultat par son ID
+        /**
+         * @swagger
+         * /exams/result/{id}:
+         *   get:
+         *     summary: Détail d'un résultat
+         *     description: Retourne un TestResult par identifiant.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Résultat trouvé
+         *       404:
+         *         description: Résultat non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/result/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             try {
@@ -716,7 +1352,21 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Lister tous les résultats
+        /**
+         * @swagger
+         * /exams/results/:
+         *   get:
+         *     summary: Lister les résultats
+         *     description: Retourne tous les résultats existants.
+         *     tags: [Résultats]
+         *     responses:
+         *       200:
+         *         description: Liste des résultats
+         *       404:
+         *         description: Aucun résultat
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/results/', authenticatedOptions, async (req, res) => {
             try {
                 const results = await TestResult.find();
@@ -730,7 +1380,35 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Créer un résultat
+        /**
+         * @swagger
+         * /exams/invite:
+         *   post:
+         *     summary: Inviter un candidat à un test
+         *     description: Crée un TestResult et envoie un email d'invitation au candidat.
+         *     tags: [Résultats]
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             required: [candidateId, testId]
+         *             properties:
+         *               candidateId:
+         *                 type: string
+         *               testId:
+         *                 type: string
+         *     responses:
+         *       201:
+         *         description: Invitation créée
+         *       404:
+         *         description: Test ou candidat non trouvé
+         *       400:
+         *         description: Paramètres manquants
+         *       500:
+         *         description: Erreur interne
+         */
         this.post('/invite', authenticatedOptions, async (req, res) => {
             const { candidateId, testId } = req.body;
             if (!candidateId || !testId) {
@@ -786,7 +1464,32 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Obtenir la question suivante
+        /**
+         * @swagger
+         * /exams/result/getNextQuestion/{id}/{idCurrentQuestion}:
+         *   get:
+         *     summary: Obtenir la question suivante
+         *     description: Retourne la prochaine question pour un TestResult ou null s'il n'y en a plus.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *       - in: path
+         *         name: idCurrentQuestion
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Prochaine question ou null
+         *       404:
+         *         description: Résultat ou test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/result/getNextQuestion/:id/:idCurrentQuestion', authenticatedOptions, async (req, res) => {
             const { id, idCurrentQuestion } = req.params;
             try {
@@ -812,7 +1515,32 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Vérifier si c'est la dernière question
+        /**
+         * @swagger
+         * /exams/result/isLastQuestion/{id}/{idCurrentQuestion}:
+         *   get:
+         *     summary: Vérifier la dernière question
+         *     description: Indique si la question courante est la dernière du test.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *       - in: path
+         *         name: idCurrentQuestion
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Booléen retourné
+         *       404:
+         *         description: Résultat ou test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/result/isLastQuestion/:id/:idCurrentQuestion', authenticatedOptions, async (req, res) => {
             const { id, idCurrentQuestion } = req.params;
             try {
@@ -837,7 +1565,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Obtenir une question
+        /**
+         * @swagger
+         * /exams/result/question/{questionId}:
+         *   get:
+         *     summary: Obtenir une question (résultat)
+         *     description: Retourne une question via son identifiant pour un résultat.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: questionId
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Question trouvée
+         *       404:
+         *         description: Question non trouvée
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/result/question/:questionId', authenticatedOptions, async (req, res) => {
             const { questionId } = req.params;
             try {
@@ -852,7 +1600,41 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Envoyer une réponse
+        /**
+         * @swagger
+         * /exams/result/sendResponse/{id}/{idCurrentQuestion}:
+         *   put:
+         *     summary: Envoyer une réponse
+         *     description: Enregistre la réponse d'un candidat pour une question d'un test.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *       - in: path
+         *         name: idCurrentQuestion
+         *         required: true
+         *         schema:
+         *           type: string
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             properties:
+         *               candidateResponse:
+         *                 type: string
+         *     responses:
+         *       200:
+         *         description: Réponse enregistrée
+         *       404:
+         *         description: Test ou résultat non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.put('/result/sendResponse/:id/:idCurrentQuestion', authenticatedOptions, async (req, res) => {
             const { id, idCurrentQuestion } = req.params;
             const { candidateResponse } = req.body;
@@ -889,7 +1671,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Corriger un test
+        /**
+         * @swagger
+         * /exams/result/correct/{id}:
+         *   post:
+         *     summary: Lancer la correction d'un test
+         *     description: Déclenche la correction d'un TestResult.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Correction lancée
+         *       404:
+         *         description: Résultat non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.post('/result/correct/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             try {
@@ -905,7 +1707,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Calculer le score
+        /**
+         * @swagger
+         * /exams/result/calculateScore/{id}:
+         *   put:
+         *     summary: Calculer le score
+         *     description: Calcule et enregistre le score final d'un TestResult.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Score calculé
+         *       404:
+         *         description: Résultat non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.put('/result/calculateScore/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             try {
@@ -948,7 +1770,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Obtenir le score maximum
+        /**
+         * @swagger
+         * /exams/maxscore/{resultId}:
+         *   get:
+         *     summary: Obtenir le score maximum
+         *     description: Calcule le score maximal possible pour un résultat.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: resultId
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Score maximum retourné
+         *       404:
+         *         description: Résultat ou test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/maxscore/:resultId', authenticatedOptions, async (req, res) => {
             const { resultId } = req.params;
             try {
@@ -974,7 +1816,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Obtenir le score d'un résultat
+        /**
+         * @swagger
+         * /exams/result/score/{id}:
+         *   get:
+         *     summary: Obtenir le score d'un résultat
+         *     description: Retourne le score calculé d'un TestResult.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Score retourné
+         *       404:
+         *         description: Résultat non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/result/score/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             try {
@@ -989,7 +1851,43 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Générer plusieurs questions pour un test
+        /**
+         * @swagger
+         * /exams/test/generateQuestions/{id}:
+         *   put:
+         *     summary: Générer des questions pour un test
+         *     description: Génère plusieurs questions (IA) pour un test donné, éventuellement filtrées par catégorie et type.
+         *     tags: [Examens]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             required: [numberOfQuestions]
+         *             properties:
+         *               numberOfQuestions:
+         *                 type: integer
+         *               category:
+         *                 type: string
+         *               questionType:
+         *                 type: string
+         *     responses:
+         *       200:
+         *         description: Questions générées
+         *       400:
+         *         description: Paramètres invalides
+         *       404:
+         *         description: Test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.put('/test/generateQuestions/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             const { numberOfQuestions, category, questionType } = req.body;
@@ -1001,6 +1899,9 @@ class ExamsRouter extends EnduranceRouter {
                 if (!test) {
                     return res.status(404).json({ message: 'Test non trouvé' });
                 }
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'Test non trouvé' });
+                }
                 let categoriesToUse = [];
                 if (category && category !== 'ALL') {
                     const categoryInfo = test.categories.find(cat => cat.categoryId.toString() === category);
@@ -1069,7 +1970,56 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Erreur interne du serveur' });
             }
         });
-        // Lister tous les candidats invités à un test
+        /**
+         * @swagger
+         * /exams/test/{testId}/candidates:
+         *   get:
+         *     summary: Lister les candidats invités
+         *     description: Liste paginée des candidats invités à un test avec filtres et tri.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: testId
+         *         required: true
+         *         schema:
+         *           type: string
+         *       - in: query
+         *         name: page
+         *         schema:
+         *           type: integer
+         *           default: 1
+         *       - in: query
+         *         name: limit
+         *         schema:
+         *           type: integer
+         *           default: 10
+         *       - in: query
+         *         name: search
+         *         schema:
+         *           type: string
+         *       - in: query
+         *         name: state
+         *         schema:
+         *           type: string
+         *           default: all
+         *       - in: query
+         *         name: sortBy
+         *         schema:
+         *           type: string
+         *           default: invitationDate
+         *       - in: query
+         *         name: sortOrder
+         *         schema:
+         *           type: string
+         *           default: desc
+         *     responses:
+         *       200:
+         *         description: Candidats paginés
+         *       404:
+         *         description: Test non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.get('/test/:testId/candidates', authenticatedOptions, async (req, res) => {
             const { testId } = req.params;
             const page = parseInt(req.query.page) || 1;
@@ -1084,6 +2034,9 @@ class ExamsRouter extends EnduranceRouter {
                 if (!test) {
                     return res.status(404).json({ message: 'Test non trouvé' });
                 }
+                if (req.entity?._id && test.entityId && !test.entityId.equals(req.entity._id)) {
+                    return res.status(404).json({ message: 'Test non trouvé' });
+                }
                 // Construction de la requête
                 const query = { testId };
                 if (state !== 'all') {
@@ -1231,7 +2184,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Erreur interne du serveur' });
             }
         });
-        // Renvoyer l'email d'invitation à un candidat
+        /**
+         * @swagger
+         * /exams/reinvite/{resultId}:
+         *   post:
+         *     summary: Renvoyer une invitation
+         *     description: Récupère un TestResult et renvoie l'email d'invitation.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: resultId
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Invitation renvoyée
+         *       404:
+         *         description: Ressource non trouvée
+         *       500:
+         *         description: Erreur interne
+         */
         this.post('/reinvite/:resultId', authenticatedOptions, async (req, res) => {
             const { resultId } = req.params;
             try {
@@ -1280,7 +2253,45 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Internal server error' });
             }
         });
-        // Correction manuelle d'une réponse à une question d'un testResult
+        /**
+         * @swagger
+         * /exams/result/{testResultId}/response/{questionId}:
+         *   put:
+         *     summary: Correction manuelle d'une réponse
+         *     description: Met à jour le score/commentaire d'une réponse et recalcule le score global.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: testResultId
+         *         required: true
+         *         schema:
+         *           type: string
+         *       - in: path
+         *         name: questionId
+         *         required: true
+         *         schema:
+         *           type: string
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             properties:
+         *               score:
+         *                 type: number
+         *               comment:
+         *                 type: string
+         *     responses:
+         *       200:
+         *         description: Correction enregistrée
+         *       404:
+         *         description: Ressource non trouvée
+         *       400:
+         *         description: Score invalide
+         *       500:
+         *         description: Erreur interne
+         */
         this.put('/result/:testResultId/response/:questionId', authenticatedOptions, async (req, res) => {
             try {
                 const { testResultId, questionId } = req.params;
@@ -1323,7 +2334,27 @@ class ExamsRouter extends EnduranceRouter {
                 res.status(500).json({ message: 'Erreur interne du serveur' });
             }
         });
-        // Supprimer un test result
+        /**
+         * @swagger
+         * /exams/result/{id}:
+         *   delete:
+         *     summary: Supprimer un résultat
+         *     description: Supprime un TestResult.
+         *     tags: [Résultats]
+         *     parameters:
+         *       - in: path
+         *         name: id
+         *         required: true
+         *         schema:
+         *           type: string
+         *     responses:
+         *       200:
+         *         description: Résultat supprimé
+         *       404:
+         *         description: Résultat non trouvé
+         *       500:
+         *         description: Erreur interne
+         */
         this.delete('/result/:id', authenticatedOptions, async (req, res) => {
             const { id } = req.params;
             try {