feat: Add detailed JSDoc comments to AgentPart and Audits schemas for improved documentation

Author: tacxou

apps/api/src/core/audits/_schemas/_parts/agent.parts.schema.ts

@@ -1,16 +1,66 @@
-import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
-import { Document, Types } from 'mongoose';
+import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose'
+import { Document, Types } from 'mongoose'
 
+/**
+ * Schéma Mongoose pour la partie Agent des audits.
+ *
+ * Ce schéma représente les informations de l'agent (utilisateur ou système)
+ * qui a effectué l'action auditée. Il est utilisé comme sous-document dans
+ * les entrées d'audit pour tracer l'origine des modifications.
+ *
+ * @class AgentPart
+ * @extends {Document}
+ *
+ * @description
+ * Structure de l'agent :
+ * - $ref : Référence au type de collection de l'agent (ex: "agents", "users", "system")
+ * - id : Identifiant unique de l'agent dans sa collection
+ * - name : Nom ou identifiant lisible de l'agent (optionnel)
+ *
+ * Note : Le schéma utilise `_id: false` car il est intégré comme sous-document
+ * dans le schéma d'audit principal et n'a pas besoin de son propre identifiant.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   $ref: "agents",
+ *   id: ObjectId("507f1f77bcf86cd799439011"),
+ *   name: "john.doe"
+ * }
+ * ```
+ */
 @Schema({ _id: false })
 export class AgentPart extends Document {
+  /**
+   * Référence au type de collection de l'agent.
+   * Indique la collection MongoDB où se trouve l'enregistrement complet de l'agent.
+   *
+   * @type {string}
+   * @example "agents", "users", "system"
+   */
   @Prop({ type: String, required: true })
-  public $ref: string;
+  public $ref: string
 
+  /**
+   * Identifiant unique de l'agent dans sa collection.
+   *
+   * @type {Types.ObjectId}
+   */
   @Prop({ type: Types.ObjectId, required: true })
-  public id: Types.ObjectId;
+  public id: Types.ObjectId
 
+  /**
+   * Nom ou identifiant lisible de l'agent.
+   * Permet une identification rapide sans avoir à faire une jointure.
+   *
+   * @type {string}
+   * @optional
+   */
   @Prop({ type: String })
-  public name?: string;
+  public name?: string
 }
 
-export const AgentPartSchema = SchemaFactory.createForClass(AgentPart);
+/**
+ * Factory pour créer le schéma Mongoose à partir de la classe AgentPart.
+ */
+export const AgentPartSchema = SchemaFactory.createForClass(AgentPart)

apps/api/src/core/audits/_schemas/audits.schema.ts

@@ -1,50 +1,150 @@
-import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
-import { Document, Types } from 'mongoose';
-import { AbstractSchema } from '~/_common/abstracts/schemas/abstract.schema';
-import { AgentPart, AgentPartSchema } from './_parts/agent.parts.schema';
-import { ChangesType } from '~/_common/plugins/mongoose/history.plugin';
+import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose'
+import { Document, Types } from 'mongoose'
+import { AbstractSchema } from '~/_common/abstracts/schemas/abstract.schema'
+import { AgentPart, AgentPartSchema } from './_parts/agent.parts.schema'
+import { ChangesType } from '~/_common/plugins/mongoose/history.plugin'
 
+/**
+ * Énumération des types d'opérations auditées.
+ *
+ * @enum {string}
+ */
 export enum AuditOperation {
+  /** Insertion d'un nouvel enregistrement */
   INSERT = 'insert',
+  /** Mise à jour d'un enregistrement existant */
   UPDATE = 'update',
+  /** Suppression d'un enregistrement */
   DELETE = 'delete',
+  /** Remplacement complet d'un enregistrement */
   REPLACE = 'replace',
 }
 
-export type AuditsDocument = Audits & Document;
+/**
+ * Type combiné pour les documents d'audit avec les fonctionnalités Mongoose.
+ */
+export type AuditsDocument = Audits & Document
 
+/**
+ * Schéma Mongoose principal pour les audits.
+ *
+ * Ce schéma stocke l'historique complet de toutes les modifications apportées
+ * aux enregistrements du système. Les entrées d'audit sont créées automatiquement
+ * par le plugin Mongoose d'historique qui intercepte les opérations de base de données.
+ *
+ * @class Audits
+ * @extends {AbstractSchema}
+ *
+ * @description
+ * Chaque entrée d'audit enregistre :
+ * - La collection et l'identifiant du document modifié
+ * - Le type d'opération effectuée (insert, update, delete, replace)
+ * - L'agent qui a effectué l'action (utilisateur ou système)
+ * - L'état complet du document après l'opération (data)
+ * - Le détail des changements pour les mises à jour (changes)
+ * - Les métadonnées héritées d'AbstractSchema (dates de création, modification, etc.)
+ *
+ * Ces informations permettent :
+ * - De consulter l'historique complet d'un enregistrement
+ * - D'auditer les actions des utilisateurs
+ * - D'effectuer un rollback en restaurant une version antérieure
+ * - D'analyser les modifications pour détecter des anomalies
+ *
+ * @example
+ * ```typescript
+ * {
+ *   coll: "users",
+ *   documentId: ObjectId("507f1f77bcf86cd799439011"),
+ *   op: "update",
+ *   agent: {
+ *     $ref: "agents",
+ *     id: ObjectId("507f1f77bcf86cd799439012"),
+ *     name: "john.doe"
+ *   },
+ *   data: { username: "john.doe", email: "new@example.com" },
+ *   changes: [],
+ *   createdAt: ISODate("2025-11-25T10:00:00Z")
+ * }
+ * ```
+ */
 @Schema({ versionKey: false, collection: 'audits' })
 export class Audits extends AbstractSchema {
+  /**
+   * Nom de la collection MongoDB du document audité.
+   * Permet d'identifier le type d'enregistrement concerné par l'audit.
+   *
+   * @type {string}
+   * @example "users", "agents", "tasks"
+   */
   @Prop({
     type: String,
     required: true,
   })
-  public coll!: string;
+  public coll!: string
 
+  /**
+   * Identifiant unique du document audité dans sa collection.
+   * Permet de retrouver l'enregistrement concerné par cette entrée d'audit.
+   *
+   * @type {Types.ObjectId}
+   */
   @Prop({
     type: Types.ObjectId,
     required: true,
   })
-  public documentId!: Types.ObjectId;
+  public documentId!: Types.ObjectId
 
+  /**
+   * Type d'opération effectuée sur le document.
+   * Détermine la nature de la modification auditée.
+   *
+   * @type {'insert' | 'update' | 'delete' | 'replace'}
+   * @see {AuditOperation}
+   */
   @Prop({
     type: String,
     required: true,
     enum: AuditOperation,
   })
-  public op!: 'insert' | 'update' | 'delete' | 'replace';
+  public op!: 'insert' | 'update' | 'delete' | 'replace'
 
+  /**
+   * Agent (utilisateur ou système) qui a effectué l'opération.
+   * Contient la référence et l'identifiant de l'agent responsable de la modification.
+   *
+   * @type {AgentPart}
+   * @see {AgentPart}
+   */
   @Prop({
     type: AgentPartSchema,
     required: true,
   })
-  public agent!: AgentPart;
+  public agent!: AgentPart
 
+  /**
+   * État complet du document après l'opération.
+   * Pour les insertions et mises à jour, contient l'état final du document.
+   * Pour les suppressions, peut contenir l'état avant suppression.
+   *
+   * @type {Document}
+   * @optional
+   */
   @Prop({ type: Object })
-  public data?: Document;
+  public data?: Document
 
+  /**
+   * Détail des changements effectués lors d'une mise à jour.
+   * Tableau contenant chaque champ modifié avec ses valeurs avant/après.
+   * Uniquement présent pour les opérations de type UPDATE.
+   *
+   * @type {ChangesType[]}
+   * @optional
+   */
   @Prop({ type: Array, of: Object })
-  public changes?: ChangesType[];
+  public changes?: ChangesType[]
 }
 
-export const AuditsSchema = SchemaFactory.createForClass(Audits);
+/**
+ * Factory pour créer le schéma Mongoose à partir de la classe Audits.
+ */
+export const AuditsSchema = SchemaFactory.createForClass(Audits)