feat: Enhance AgentsService and AuditsModule with detailed JSDoc comments for improved documentation

Author: tacxou

apps/api/src/core/agents/agents.service.ts

@@ -101,23 +101,15 @@ export class AgentsService extends AbstractServiceSchema {
     update: UpdateQuery<T> & any,
     options?: QueryOptions<T>,
   ): Promise<ModifyResult<Query<T, T, any, T>>> {
-    if (update.password) {
-      update.password = await hash(update.password)
-    }
+    // Hachage du mot de passe si présent
+    if (update.password) update.password = await hash(update.password)
+    if (update.$set?.password) update.$set.password = await hash(update.$set.password)
 
-    if (update.$set?.password) {
-      update.$set.password = await hash(update.$set.password)
+    // Log si le mot de passe est mis à jour
+    if (update.password || update.$set?.password) {
+      this.logger.verbose(`Updating password for agent with ID: ${_id}`)
     }
 
-    return await super.update(
-      _id,
-      {
-        ...update,
-        $set: {
-          ...(update?.$set || {}),
-        },
-      },
-      options,
-    )
+    return await super.update(_id, update, options)
   }
 }

apps/api/src/core/audits/audits.module.ts

@@ -1,9 +1,42 @@
-import { Module } from '@nestjs/common';
-import { MongooseModule } from '@nestjs/mongoose';
-import { AuditsSchema, Audits } from '~/core/audits/_schemas/audits.schema';
-import { AuditsService } from './audits.service';
-import { AuditsController } from './audits.controller';
+import { Module } from '@nestjs/common'
+import { MongooseModule } from '@nestjs/mongoose'
+import { AuditsSchema, Audits } from '~/core/audits/_schemas/audits.schema'
+import { AuditsService } from './audits.service'
+import { AuditsController } from './audits.controller'
 
+/**
+ * Module de gestion des audits et de l'historique des enregistrements.
+ *
+ * Ce module fournit un système de logging en base de données où l'enregistrement
+ * automatique de l'historique des modifications est géré par un plugin Mongoose.
+ * Le module expose des fonctionnalités pour lister, restaurer et supprimer les
+ * entrées d'audit capturées automatiquement.
+ *
+ * @module AuditsModule
+ *
+ * @description
+ * Architecture du système :
+ * - **Plugin Mongoose** : Intercepte automatiquement toutes les opérations de base de données
+ *   (création, mise à jour, suppression) et enregistre les traces d'audit avec l'état
+ *   complet avant/après modification
+ * - **Service AuditsService** : Permet de lister, restaurer et supprimer les entrées d'audit
+ * - **Contrôleur AuditsController** : Expose les endpoints API REST pour consulter l'historique
+ *   et effectuer des opérations de restauration
+ *
+ * Fonctionnalités principales :
+ * - Enregistrement automatique de l'historique via plugin Mongoose (transparent)
+ * - Consultation de l'historique complet des modifications d'un enregistrement
+ * - Restauration (rollback) d'une version antérieure d'un enregistrement
+ * - Suppression d'entrées d'audit obsolètes ou non nécessaires
+ * - Traçabilité complète des actions effectuées avec métadonnées
+ *
+ * Le module configure :
+ * - La connexion à la base de données MongoDB via Mongoose pour le modèle Audits
+ * - Le service AuditsService pour les opérations de consultation, restauration et suppression
+ * - Le contrôleur AuditsController pour les endpoints API REST
+ *
+ * @exports AuditsService - Expose le service pour être utilisé par d'autres modules
+ */
 @Module({
   imports: [
     MongooseModule.forFeatureAsync([

apps/api/src/core/audits/audits.service.ts

@@ -1,12 +1,38 @@
-import { Injectable } from '@nestjs/common';
-import { InjectModel } from '@nestjs/mongoose';
-import { Audits } from '~/core/audits/_schemas/audits.schema';
-import { Model } from 'mongoose';
-import { AbstractServiceSchema } from '~/_common/abstracts/abstract.service.schema';
+import { Injectable } from '@nestjs/common'
+import { InjectModel } from '@nestjs/mongoose'
+import { Audits } from '~/core/audits/_schemas/audits.schema'
+import { Model } from 'mongoose'
+import { AbstractServiceSchema } from '~/_common/abstracts/abstract.service.schema'
 
+/**
+ * Service de gestion des audits et de l'historique des enregistrements.
+ *
+ * Ce service permet de consulter, restaurer et supprimer les entrées d'audit
+ * qui sont automatiquement enregistrées en base de données par un plugin Mongoose.
+ * Le plugin capture automatiquement toutes les modifications (création, mise à jour,
+ * suppression) et enregistre l'état complet avant/après modification.
+ *
+ * @class AuditsService
+ * @extends {AbstractServiceSchema}
+ *
+ * @description
+ * Fonctionnalités du service :
+ * - **Lister** : Consulter l'historique complet des modifications d'un enregistrement
+ * - **Restaurer** : Effectuer un rollback en restaurant une version antérieure d'un enregistrement
+ * - **Supprimer** : Nettoyer les entrées d'audit obsolètes ou non nécessaires
+ *
+ * Note : L'enregistrement automatique des audits est géré par un plugin Mongoose
+ * qui intercepte les opérations de base de données et crée les traces d'audit
+ * de manière transparente.
+ */
 @Injectable()
 export class AuditsService extends AbstractServiceSchema {
+  /**
+   * Constructeur du service AuditsService.
+   *
+   * @param {Model<Audits>} _model - Le modèle Mongoose pour la collection des audits
+   */
   constructor(@InjectModel(Audits.name) protected _model: Model<Audits>) {
-    super();
+    super()
   }
 }