Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

TP 9 : Gestion de documents (upload) et notifications par email

Ce TP prolonge le dépôt GitHub du TP 8 (API de scolarité sécurisée) avec la gestion de documents. Les stagiaires déposent des documents PDF, PNG ou JPEG de 5 Mo au maximum, vérifiés d'après leur conte...

0 chapitres 0 QCM Accès gratuit
TP 9 : Gestion de documents (upload) et notifications par email

À propos de ce cours

Ce TP prolonge le dépôt GitHub du TP 8 (API de scolarité sécurisée) avec la gestion de documents. Les stagiaires déposent des documents PDF, PNG ou JPEG de 5 Mo au maximum, vérifiés d'après leur contenu et stockés sous un nom aléatoire. Chacun ne voit et ne télécharge que ce que son rôle permet. Chaque dépôt déclenche un événement qui envoie un e-mail au formateur du groupe, testé avec MailDev. Les statistiques sont mises en cache et invalidées. Des tâches planifiées suppriment les fichiers orphelins et envoient un bilan hebdomadaire. Migration, correction exécutée et grille sur 20.

Objectifs du TP

  • Recevoir, valider et stocker des fichiers de façon sûre.
  • Distribuer des fichiers privés selon les rôles et la propriété.
  • Envoyer des notifications par e-mail sans ralentir ni casser les requêtes, grâce aux événements.
  • Utiliser le cache et les tâches planifiées dans un vrai projet.
  • Faire évoluer une base existante avec une nouvelle migration et livrer une nouvelle version sur GitHub.

Durée: 6 h  |  Prérequis: TP 8 terminé, leçons 15.1 à 15.6  |  Livrable: le dépôt api-scolarite-securisee avec l'étiquette v1.1.0.

Architecture du TP 9

Un module documents branché sur l'authentification du TP 8, le courrier, le cache et les tâches.

Cahier des charges
RouteQuiRègle
POST /api/documentsstagiairePDF, PNG ou JPEG détecté d'après le contenu ; 5 Mo au maximum ; stocké sous <uuid>.<ext> hors du dossier public
GET /api/documentstousstagiaire : les siens ; formateur : ceux des stagiaires de ses groupes ; admin : tous (filtré en SQL)
GET /api/documents/:id/fichiertousmêmes règles ; 403 sinon, 404 si inexistant ; nom d'origine dans Content-Disposition
DELETE /api/documents/:idpropriétaire, adminsupprime la ligne et le fichier ; un formateur ne supprime pas
GET /api/documents/statistiquesadminnombre et volume par type ; en cache 10 min, invalidé à chaque dépôt ou suppression
  • Chaque dépôt envoie un e-mail au formateur du groupe du stagiaire. Une panne d'e-mail ne doit jamais faire échouer le dépôt.
  • Chaque nuit à 3 h (heure de Tunis) : suppression des fichiers du disque qui ne correspondent à aucun document. Chaque lundi à 8 h : bilan de la semaine envoyé aux administrateurs.
  • Le dossier stockage/ n'est jamais versionné.
Partie 1 Reprendre le dépôt du TP 8
  1. Dans votre dépôt api-scolarite-securisee, créez une branche : git switch -c tp9-documents.
  2. Installez les dépendances : npm install @nestjs/cache-manager cache-manager @nestjs/event-emitter @nestjs/schedule nodemailer et npm install -D @types/multer @types/nodemailer.
  3. Dans tsconfig.json, ajoutez "multer" à types. Si votre projet a été créé avec NestJS 12 (TypeScript 6), vérifiez que les interfaces utilisées dans les signatures décorées sont importées avec type (import { Utilisateur, type UtilisateurConnecte } from …).
  4. Ajoutez stockage/ à .gitignore; complétez .env et .env.example; lancez npx maildev dans un terminal.
  5. Commit : chore: dépendances et configuration du TP 9.
# Ajouts au .env du TP 8 (et noms sans valeurs dans .env.example)
MAIL_HOTE=127.0.0.1
MAIL_PORT=1025
MAIL_SECURISE=false
MAIL_UTILISATEUR=
MAIL_MOT_DE_PASSE=
MAIL_EXPEDITEUR="Centre de formation <ne-pas-repondre@formation.tn>"
STOCKAGE_DOSSIER=stockage/documents
Partie 2 Entité et migration
  1. Entité Document: identifiant uuid, nom d'origine, nom stocké (unique, select: false), type, taille, propriétaire (onDelete: 'CASCADE'), date de dépôt.
  2. npm run build puis npm run migration:generate --name=AjoutDocuments. Relisez la migration avant de l'exécuter (voir le résultat attendu).
  3. npm run migration:run. Commit : db: table documents.
Partie 3 Dépôt, liste, téléchargement, suppression
  1. DocumentsService.deposer: écriture du buffer sous un nom généré, puis enregistrement en base.
  2. DocumentsController: FileInterceptor avec une limite Multer, ParseFilePipe (taille, type par signature, overrideMimeType), @Roles(Role.Stagiaire).
  3. lister filtré dans la requête SQL ; trouverAutorise commun au téléchargement et à la suppression ; StreamableFile avec Content-Disposition.
  4. Commit : feat: dépôt et consultation de documents.
Partie 4 Notifications par e-mail
  1. MailModule global et MailService (leçon 15.3), configurés par le .env.
  2. Classe DocumentDeposeEvent; emit à la fin de deposer.
  3. DocumentsListener: @OnEvent(…, { async: true }), recherche du formateur du groupe, e-mail avec données échappées, try/catch qui journalise.
  4. Vérifiez dans MailDev, puis arrêtez MailDev et vérifiez que le dépôt réussit toujours. Commit : feat: notification du formateur.
Partie 5 Cache et tâches planifiées
  1. CacheModule.register({ isGlobal: true }); statistiques avec le cache manuel (clé documents:statistiques), invalidées dans deposer et supprimer.
  2. ScheduleModule.forRoot(); DocumentsTaches: nettoyerOrphelins (3 h, waitForCompletion) et bilanHebdomadaire (lundi 8 h), avec le fuseau Africa/Tunis.
  3. Commit : feat: statistiques en cache et tâches planifiées.
Partie 6 Tester, documenter, livrer
  1. Complétez requetes/documents.http (base ci-dessous) : tous les refus du cahier des charges (400, 401, 403, 404).
  2. Testez les tâches en appelant leurs méthodes depuis un petit script, ou avec une route d'administration temporaire.
  3. Documentez les routes avec Swagger (chapitre 14) : @ApiConsumes('multipart/form-data') et @ApiBody({ schema: { type: 'object', properties: { fichier: { type: 'string', format: 'binary' } } } }) pour le dépôt.
  4. README : configuration e-mail (MailDev, Gmail), dossier de stockage, tâches planifiées. Fusionnez la branche, poussez, étiquette v1.1.0.
@base = http://localhost:3000/api

### Connexion de Sami (stagiaire du groupe DEV101)
# @name sami
POST {{base}}/auth/connexion
Content-Type: application/json

{ "email": "sami@exemple.tn", "motDePasse": "Stagiaire2026" }

### Déposer un document (le fichier ./fichiers/attestation.pdf doit exister)
# @name depot
POST {{base}}/documents
Authorization: Bearer {{sami.response.body.access_token}}
Content-Type: multipart/form-data; boundary=LIMITE

--LIMITE
Content-Disposition: form-data; name="fichier"; filename="Attestation de stage.pdf"
Content-Type: application/pdf

< ./fichiers/attestation.pdf
--LIMITE--

### Mes documents
GET {{base}}/documents
Authorization: Bearer {{sami.response.body.access_token}}

### Télécharger
GET {{base}}/documents/{{depot.response.body.id}}/fichier
Authorization: Bearer {{sami.response.body.access_token}}
Résultat attendu

Migration et requêtes exécutées avec la correction (les comptes et groupes sont créés comme dans le TP 8) :

(dépôt du TP 8 prêt : base migrée, admin créé)

$ npm run build && npm run migration:generate --name=AjoutDocuments
Migration src/migrations/1794744355580-AjoutDocuments.ts has been generated successfully.

$ cat src/migrations/*-AjoutDocuments.ts
import { MigrationInterface, QueryRunner } from "typeorm";

export class AjoutDocuments1794744355580 implements MigrationInterface {
    name = 'AjoutDocuments1794744355580'

    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`CREATE TABLE \`documents\` (\`id\` varchar(36) NOT NULL, \`nom_original\` varchar(200) NOT NULL, \`nom_stocke\` varchar(60) NOT NULL, \`type\` varchar(50) NOT NULL, \`taille\` int NOT NULL, \`proprietaire_id\` int NOT NULL, \`depose_le\` datetime(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6), UNIQUE INDEX \`IDX_fc444d35114eb2f5dd497d770f\` (\`nom_stocke\`), PRIMARY KEY (\`id\`)) ENGINE=InnoDB`);
        await queryRunner.query(`ALTER TABLE \`utilisateurs\` DROP FOREIGN KEY \`FK_8c538cf781e0b362a56a378ee2a\``);
        await queryRunner.query(`ALTER TABLE \`utilisateurs\` CHANGE \`groupe_id\` \`groupe_id\` int NULL`);
        await queryRunner.query(`ALTER TABLE \`utilisateurs\` CHANGE \`refresh_hache\` \`refresh_hache\` char(64) NULL`);
        await queryRunner.query(`ALTER TABLE \`utilisateurs\` ADD CONSTRAINT \`FK_8c538cf781e0b362a56a378ee2a\` FOREIGN KEY (\`groupe_id\`) REFERENCES \`groupes\`(\`id\`) ON DELETE SET NULL ON UPDATE NO ACTION`);
        await queryRunner.query(`ALTER TABLE \`documents\` ADD CONSTRAINT \`FK_20a29c9e5916ecae18908ada6ec\` FOREIGN KEY (\`proprietaire_id\`) REFERENCES \`utilisateurs\`(\`id\`) ON DELETE CASCADE ON UPDATE NO ACTION`);
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`ALTER TABLE \`documents\` DROP FOREIGN KEY \`FK_20a29c9e5916ecae18908ada6ec\``);
        await queryRunner.query(`ALTER TABLE \`utilisateurs\` DROP FOREIGN KEY \`FK_8c538cf781e0b362a56a378ee2a\``);
        await queryRunner.query(`ALTER TABLE \`utilisateurs\` CHANGE \`refresh_hache\` \`refresh_hache\` char(64) NULL DEFAULT 'NULL'`);
        await queryRunner.query(`ALTER TABLE \`utilisateurs\` CHANGE \`groupe_id\` \`groupe_id\` int NULL DEFAULT 'NULL'`);
        await queryRunner.query(`ALTER TABLE \`utilisateurs\` ADD CONSTRAINT \`FK_8c538cf781e0b362a56a378ee2a\` FOREIGN KEY (\`groupe_id\`) REFERENCES \`groupes\`(\`id\`) ON DELETE SET NULL ON UPDATE NO ACTION`);
        await queryRunner.query(`DROP INDEX \`IDX_fc444d35114eb2f5dd497d770f\` ON \`documents\``);
        await queryRunner.query(`DROP TABLE \`documents\``);
    }

}

$ npm run build && npm run migration:run
1 migrations are already loaded in the database.
2 migrations were found in the source code.
Initialisation1794744348852 is the last executed migration. It was executed on Sun Nov 15 2026 13:05:48 GMT+0100 (GMT+01:00).
1 migrations are new migrations must be executed.
Migration AjoutDocuments1794744355580 has been executed successfully.

$ requêtes de test
[MailService] serveur SMTP joignable
— Mise en place (comptes et groupes du TP 8)
admin (1), Lina formatrice DEV101 (2), Omar formateur RES201 (3), Sami stagiaire DEV101 (4), Ines stagiaire RES201 (5)

— Dépôts
POST /api/documents → 201 {"id":"94e10ee9-e539-485c-b456-ea59d7be6369","nomOriginal":"Attestation de stage.pdf","type":"application/pdf","taille":209,"proprietaireId":4,"deposeLe":"2026-11-15T12:06:01.119Z"}
POST /api/documents → 201 {"id":"ccfe1187-ca37-4320-bd5d-83032cd6d0ca","nomOriginal":"CIN recto.png","type":"image/png","taille":216,"proprietaireId":5,"deposeLe":"2026-11-15T12:06:01.146Z"}
POST /api/documents → 400 {"message":"Validation failed (file type could not be detected from its content; expected type is /^(application\\/pdf|image\\/png|image\\/jpeg)$/)","error":"Bad Request","statusCode":400}
POST /api/documents → 400 {"message":"Document trop volumineux (5 Mo maximum)","error":"Bad Request","statusCode":400}
POST /api/documents → 403 {"message":"Accès réservé : stagiaire","error":"Forbidden","statusCode":403}
POST /api/documents → 400 {"message":"File is required","error":"Bad Request","statusCode":400}

— Listes selon le rôle
Sami  → 200 Attestation de stage.pdf (Sami Ben Ali)
Lina  → 200 Attestation de stage.pdf (Sami Ben Ali)
Omar  → 200 CIN recto.png (Ines Trabelsi)
admin → 200 CIN recto.png (Ines Trabelsi), Attestation de stage.pdf (Sami Ben Ali)

— Téléchargement
GET /api/documents/94e10ee9-e539-485c-b456-ea59d7be6369/fichier → 200 <209 octets binaires>  [content-type: application/pdf]  [content-disposition: attachment; filename="document.pdf"; filename*=UTF-8''Attestation%20de%20stage.pdf]
GET /api/documents/94e10ee9-e539-485c-b456-ea59d7be6369/fichier → 200 <209 octets binaires>  [content-type: application/pdf]
GET /api/documents/94e10ee9-e539-485c-b456-ea59d7be6369/fichier → 403 {"message":"Accès refusé à ce document","error":"Forbidden","statusCode":403}
GET /api/documents/94e10ee9-e539-485c-b456-ea59d7be6369/fichier → 403 {"message":"Accès refusé à ce document","error":"Forbidden","statusCode":403}
GET /api/documents/94e10ee9-e539-485c-b456-ea59d7be6369/fichier → 401 {"message":"Unauthorized","statusCode":401}
GET /api/documents/00000000-0000-4000-8000-000000000000/fichier → 404 {"message":"Document introuvable","error":"Not Found","statusCode":404}

— Statistiques (admin, en cache, invalidées à chaque dépôt)
GET /api/documents/statistiques → 200 {"parType":[{"type":"application/pdf","nombre":1,"octets":209},{"type":"image/png","nombre":1,"octets":216}],"source":"base"}
GET /api/documents/statistiques → 200 {"parType":[{"type":"application/pdf","nombre":1,"octets":209},{"type":"image/png","nombre":1,"octets":216}],"source":"cache"}
GET /api/documents/statistiques → 403 {"message":"Accès réservé : admin","error":"Forbidden","statusCode":403}
GET /api/documents/statistiques → 200 {"parType":[{"type":"application/pdf","nombre":1,"octets":209},{"type":"image/jpeg","nombre":1,"octets":111},{"type":"image/png","nombre":1,"octets":216}],"source":"base"}

— Suppression
DELETE /api/documents/94e10ee9-e539-485c-b456-ea59d7be6369 → 403 {"message":"Accès refusé à ce document","error":"Forbidden","statusCode":403}
DELETE /api/documents/94e10ee9-e539-485c-b456-ea59d7be6369 → 403 {"message":"Un formateur ne peut pas supprimer un document","error":"Forbidden","statusCode":403}
DELETE /api/documents/94e10ee9-e539-485c-b456-ea59d7be6369 → 204 <0 octets binaires>
GET /api/documents/94e10ee9-e539-485c-b456-ea59d7be6369/fichier → 404 {"message":"Document introuvable","error":"Not Found","statusCode":404}

— Tâches planifiées (appelées directement pour le test)
fichiers sur le disque avant : 4
nettoyerOrphelins() → 2 fichier(s) supprimé(s)
fichiers sur le disque après : 2

— E-mails reçus par MailDev
À : mansouri@exemple.tn | Nouveau document de Sami Ben Ali | Bonjour Lina Mansouri, Sami Ben Ali (groupe DEV101) a déposé le document « Attestation de stage.pdf ».
À : jlassi@exemple.tn | Nouveau document de Ines Trabelsi | Bonjour Omar Jlassi, Ines Trabelsi (groupe RES201) a déposé le document « CIN recto.png ».
À : mansouri@exemple.tn | Nouveau document de Sami Ben Ali | Bonjour Lina Mansouri, Sami Ben Ali (groupe DEV101) a déposé le document « releve.jpg ».
À : admin@exemple.tn | Bilan hebdomadaire : 2 document(s) déposé(s) | 2 document(s) déposé(s) depuis le 08/11/2026.

À vérifier dans vos résultats :

  • Le texte renommé en .pdf et le fichier de 6 Mo sont refusés ; un formateur ne peut pas déposer.
  • Chacun voit la bonne liste : Lina voit le document de Sami (son groupe), pas celui d'Ines ; Omar l'inverse.
  • Omar et Ines reçoivent 403 sur le document de Sami ; sans jeton, 401.
  • Les statistiques viennent de la base, puis du cache, puis à nouveau de la base après un dépôt.
  • Seuls les deux fichiers orphelins ajoutés à la main sont supprimés.
  • MailDev contient un e-mail par dépôt, adressé au bon formateur, et le bilan pour l'admin.

La migration générée contient plus que la table documents: avec MariaDB, TypeORM propose aussi de « modifier » les colonnes groupe_id et refresh_hache de utilisateurs, qui n'ont pourtant pas changé (il lit leur valeur par défaut NULL comme une chaîne 'NULL'). Ces lignes sont sans effet, mais une migration doit être relue et ne contenir que ce qui est voulu : supprimez-les dans up et dans down avant de l'exécuter et de la commiter.

Pour aller plus loin
  • Quota : 20 documents ou 50 Mo par stagiaire, vérifié dans le service avant l'écriture (409 au-delà).
  • Remplacement de la tâche de nettoyage par une suppression en deux temps (corbeille de 30 jours).
  • Miniatures des images avec la bibliothèque sharp, générées par un auditeur asynchrone.
  • Stockage dans un service objet compatible S3 (MinIO en local) au lieu du disque du serveur.
  • Mise en cache des statistiques dans Redis (leçon 15.5).
Correction
src/documents/document.entity.ts
import { Column, CreateDateColumn, Entity, JoinColumn, ManyToOne, PrimaryGeneratedColumn } from 'typeorm';
import { Utilisateur } from '../utilisateurs/utilisateur.entity';

@Entity('documents')
export class Document {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column({ name: 'nom_original', length: 200 })
  nomOriginal: string;

  // Nom sur le disque : <uuid>.<extension>, jamais le nom envoyé par le client
  @Column({ name: 'nom_stocke', length: 60, unique: true, select: false })
  nomStocke: string;

  @Column({ length: 50 })
  type: string;

  @Column({ type: 'int' })
  taille: number;

  @ManyToOne(() => Utilisateur, { nullable: false, onDelete: 'CASCADE' })
  @JoinColumn({ name: 'proprietaire_id' })
  proprietaire: Utilisateur;

  @Column({ name: 'proprietaire_id' })
  proprietaireId: number;

  @CreateDateColumn({ name: 'depose_le' })
  deposeLe: Date;
}
src/documents/document-depose.event.ts
export class DocumentDeposeEvent {
  static readonly NOM = 'document.depose';
  constructor(
    public readonly documentId: string,
    public readonly nomOriginal: string,
    public readonly proprietaireId: number,
  ) {}
}
src/documents/documents.service.ts
import { CACHE_MANAGER } from '@nestjs/cache-manager';
import { ForbiddenException, Inject, Injectable, NotFoundException, StreamableFile } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { EventEmitter2 } from '@nestjs/event-emitter';
import { InjectRepository } from '@nestjs/typeorm';
import type { Cache } from 'cache-manager';
import { randomUUID } from 'node:crypto';
import { createReadStream } from 'node:fs';
import { mkdir, unlink, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import { Repository } from 'typeorm';
import type { UtilisateurConnecte } from '../auth/decorators';
import { Role } from '../utilisateurs/utilisateur.entity';
import { DocumentDeposeEvent } from './document-depose.event';
import { Document } from './document.entity';

export const EXTENSIONS: Record<string, string> = { 'application/pdf': '.pdf', 'image/png': '.png', 'image/jpeg': '.jpg' };
const CLE_STATS = 'documents:statistiques';

@Injectable()
export class DocumentsService {
  readonly dossier: string;

  constructor(
    @InjectRepository(Document) private readonly documents: Repository<Document>,
    private readonly evenements: EventEmitter2,
    @Inject(CACHE_MANAGER) private readonly cache: Cache,
    config: ConfigService,
  ) {
    this.dossier = config.get('STOCKAGE_DOSSIER', 'stockage/documents');
  }

  async deposer(fichier: Express.Multer.File, moi: UtilisateurConnecte) {
    await mkdir(this.dossier, { recursive: true });
    const nomStocke = randomUUID() + EXTENSIONS[fichier.mimetype];
    await writeFile(join(this.dossier, nomStocke), fichier.buffer);
    const doc = await this.documents.save(
      this.documents.create({ nomOriginal: fichier.originalname, nomStocke, type: fichier.mimetype, taille: fichier.size, proprietaireId: moi.id }),
    );
    await this.cache.del(CLE_STATS);
    this.evenements.emit(DocumentDeposeEvent.NOM, new DocumentDeposeEvent(doc.id, doc.nomOriginal, moi.id));
    const { nomStocke: _, ...visible } = doc;
    return visible;
  }

  // Règle de propriété (comme les notes du TP 8), appliquée dans la requête SQL
  lister(moi: UtilisateurConnecte) {
    const qb = this.documents.createQueryBuilder('d')
      .innerJoin('d.proprietaire', 'p').addSelect(['p.id', 'p.nom'])
      .leftJoin('p.groupe', 'g')
      .orderBy('d.deposeLe', 'DESC');
    if (moi.role === Role.Stagiaire) qb.where('d.proprietaireId = :id', { id: moi.id });
    if (moi.role === Role.Formateur) qb.where('g.formateurId = :id', { id: moi.id });
    return qb.getMany();
  }

  private async trouverAutorise(id: string, moi: UtilisateurConnecte) {
    const doc = await this.documents.createQueryBuilder('d')
      .addSelect('d.nomStocke')
      .innerJoinAndSelect('d.proprietaire', 'p')
      .leftJoinAndSelect('p.groupe', 'g')
      .where('d.id = :id', { id })
      .getOne();
    if (!doc) throw new NotFoundException('Document introuvable');
    const autorise =
      moi.role === Role.Admin ||
      doc.proprietaireId === moi.id ||
      (moi.role === Role.Formateur && doc.proprietaire.groupe?.formateurId === moi.id);
    if (!autorise) throw new ForbiddenException('Accès refusé à ce document');
    return doc;
  }

  async telecharger(id: string, moi: UtilisateurConnecte) {
    const doc = await this.trouverAutorise(id, moi);
    return new StreamableFile(createReadStream(join(this.dossier, doc.nomStocke)), {
      type: doc.type,
      length: doc.taille,
      disposition: `attachment; filename="document${doc.nomStocke.slice(-4)}"; filename*=UTF-8''${encodeURIComponent(doc.nomOriginal)}`,
    });
  }

  async supprimer(id: string, moi: UtilisateurConnecte) {
    const doc = await this.trouverAutorise(id, moi);
    if (moi.role === Role.Formateur) throw new ForbiddenException('Un formateur ne peut pas supprimer un document');
    await this.documents.delete(doc.id);
    await unlink(join(this.dossier, doc.nomStocke)).catch(() => undefined);
    await this.cache.del(CLE_STATS);
  }

  async statistiques() {
    const enCache = await this.cache.get<object>(CLE_STATS);
    if (enCache) return { ...enCache, source: 'cache' };
    const parType = await this.documents.createQueryBuilder('d')
      .select('d.type', 'type').addSelect('COUNT(*)', 'nombre').addSelect('SUM(d.taille)', 'octets')
      .groupBy('d.type').orderBy('d.type').getRawMany<{ type: string; nombre: string; octets: string }>();
    const stats = { parType: parType.map((t) => ({ type: t.type, nombre: Number(t.nombre), octets: Number(t.octets) })) };
    await this.cache.set(CLE_STATS, stats, 10 * 60_000);
    return { ...stats, source: 'base' };
  }
}
src/documents/documents.controller.ts
import {
  Controller, Delete, FileTypeValidator, Get, HttpCode, MaxFileSizeValidator, Param, ParseFilePipe, ParseUUIDPipe,
  Post, UploadedFile, UseInterceptors,
} from '@nestjs/common';
import { FileInterceptor } from '@nestjs/platform-express';
import { Roles, Utilisateur, type UtilisateurConnecte } from '../auth/decorators';
import { Role } from '../utilisateurs/utilisateur.entity';
import { DocumentsService } from './documents.service';

@Controller('documents')
export class DocumentsController {
  constructor(private readonly service: DocumentsService) {}

  @Post()
  @Roles(Role.Stagiaire)
  @UseInterceptors(FileInterceptor('fichier', { limits: { fileSize: 10 * 1024 * 1024 } }))
  deposer(
    @UploadedFile(
      new ParseFilePipe({
        validators: [
          new MaxFileSizeValidator({ maxSize: 5 * 1024 * 1024, errorMessage: 'Document trop volumineux (5 Mo maximum)' }),
          new FileTypeValidator({ fileType: /^(application\/pdf|image\/png|image\/jpeg)$/, overrideMimeType: true }),
        ],
      }),
    )
    fichier: Express.Multer.File,
    @Utilisateur() moi: UtilisateurConnecte,
  ) {
    return this.service.deposer(fichier, moi);
  }

  @Get()
  lister(@Utilisateur() moi: UtilisateurConnecte) {
    return this.service.lister(moi);
  }

  @Get('statistiques')
  @Roles(Role.Admin)
  statistiques() {
    return this.service.statistiques();
  }

  @Get(':id/fichier')
  telecharger(@Param('id', ParseUUIDPipe) id: string, @Utilisateur() moi: UtilisateurConnecte) {
    return this.service.telecharger(id, moi);
  }

  @Delete(':id')
  @HttpCode(204)
  supprimer(@Param('id', ParseUUIDPipe) id: string, @Utilisateur() moi: UtilisateurConnecte) {
    return this.service.supprimer(id, moi);
  }
}
src/documents/documents.listener.ts
import { Injectable, Logger } from '@nestjs/common';
import { OnEvent } from '@nestjs/event-emitter';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { MailService } from '../mail/mail.service';
import { echapper } from '../mail/modeles';
import { Utilisateur } from '../utilisateurs/utilisateur.entity';
import { DocumentDeposeEvent } from './document-depose.event';

@Injectable()
export class DocumentsListener {
  private readonly logger = new Logger(DocumentsListener.name);

  constructor(
    @InjectRepository(Utilisateur) private readonly utilisateurs: Repository<Utilisateur>,
    private readonly mail: MailService,
  ) {}

  // Prévenir le formateur du groupe ; un échec d'envoi ne doit jamais faire échouer le dépôt
  @OnEvent(DocumentDeposeEvent.NOM, { async: true })
  async prevenirFormateur(e: DocumentDeposeEvent) {
    try {
      const stagiaire = await this.utilisateurs.findOne({ where: { id: e.proprietaireId }, relations: { groupe: { formateur: true } } });
      const formateur = stagiaire?.groupe?.formateur;
      if (!stagiaire || !formateur) return;
      await this.mail.envoyer({
        a: formateur.email,
        sujet: `Nouveau document de ${stagiaire.nom}`,
        html: `<p>Bonjour ${echapper(formateur.nom)},</p>
<p><strong>${echapper(stagiaire.nom)}</strong> (groupe ${echapper(stagiaire.groupe!.code)}) a déposé le document
« ${echapper(e.nomOriginal)} ».</p>`,
      });
    } catch (err) {
      this.logger.error(`Notification du dépôt ${e.documentId} impossible : ${(err as Error).message}`);
    }
  }
}
src/documents/documents.taches.ts
import { Injectable, Logger } from '@nestjs/common';
import { Cron } from '@nestjs/schedule';
import { InjectRepository } from '@nestjs/typeorm';
import { readdir, unlink } from 'node:fs/promises';
import { join } from 'node:path';
import { MoreThan, Repository } from 'typeorm';
import { MailService } from '../mail/mail.service';
import { Role, Utilisateur } from '../utilisateurs/utilisateur.entity';
import { Document } from './document.entity';
import { DocumentsService } from './documents.service';

@Injectable()
export class DocumentsTaches {
  private readonly logger = new Logger(DocumentsTaches.name);

  constructor(
    @InjectRepository(Document) private readonly documents: Repository<Document>,
    @InjectRepository(Utilisateur) private readonly utilisateurs: Repository<Utilisateur>,
    private readonly service: DocumentsService,
    private readonly mail: MailService,
  ) {}

  // Chaque nuit à 3 h : supprimer les fichiers du disque qui ne correspondent à aucun document
  @Cron('0 0 3 * * *', { name: 'nettoyage-documents', timeZone: 'Africa/Tunis', waitForCompletion: true })
  async nettoyerOrphelins() {
    const connus = new Set(
      (await this.documents.find({ select: { id: true, nomStocke: true } })).map((d) => d.nomStocke),
    );
    const fichiers = await readdir(this.service.dossier).catch(() => [] as string[]);
    const orphelins = fichiers.filter((f) => !connus.has(f));
    for (const f of orphelins) await unlink(join(this.service.dossier, f));
    this.logger.log(`Nettoyage : ${orphelins.length} fichier(s) orphelin(s) supprimé(s)`);
    return orphelins.length;
  }

  // Chaque lundi à 8 h : bilan de la semaine aux administrateurs
  @Cron('0 0 8 * * 1', { name: 'bilan-hebdomadaire', timeZone: 'Africa/Tunis' })
  async bilanHebdomadaire() {
    const depuis = new Date(Date.now() - 7 * 24 * 3600 * 1000);
    const nombre = await this.documents.countBy({ deposeLe: MoreThan(depuis) });
    const admins = await this.utilisateurs.findBy({ role: Role.Admin, actif: true });
    if (!admins.length) return;
    await this.mail.envoyer({
      a: admins.map((a) => a.email),
      sujet: `Bilan hebdomadaire : ${nombre} document(s) déposé(s)`,
      html: `<p>${nombre} document(s) déposé(s) depuis le ${depuis.toLocaleDateString('fr-TN')}.</p>`,
    });
  }
}
src/documents/documents.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { Utilisateur } from '../utilisateurs/utilisateur.entity';
import { Document } from './document.entity';
import { DocumentsController } from './documents.controller';
import { DocumentsListener } from './documents.listener';
import { DocumentsService } from './documents.service';
import { DocumentsTaches } from './documents.taches';

@Module({
  imports: [TypeOrmModule.forFeature([Document, Utilisateur])],
  controllers: [DocumentsController],
  providers: [DocumentsService, DocumentsListener, DocumentsTaches],
})
export class DocumentsModule {}
src/mail/mail.service.ts
import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { createTransport, SendMailOptions, Transporter } from 'nodemailer';

export interface Message {
  a: string | string[];
  sujet: string;
  html: string;
  texte?: string;
  piecesJointes?: SendMailOptions['attachments'];
}

@Injectable()
export class MailService implements OnModuleInit {
  private readonly logger = new Logger(MailService.name);
  private readonly transporteur: Transporter;
  private readonly expediteur: string;

  constructor(config: ConfigService) {
    const utilisateur = config.get<string>('MAIL_UTILISATEUR');
    this.transporteur = createTransport({
      host: config.getOrThrow<string>('MAIL_HOTE'),
      port: Number(config.getOrThrow('MAIL_PORT')),
      secure: config.get('MAIL_SECURISE') === 'true',          // true pour le port 465 (SSL/TLS)
      auth: utilisateur ? { user: utilisateur, pass: config.get<string>('MAIL_MOT_DE_PASSE') } : undefined,
      connectionTimeout: 5000,
    });
    this.expediteur = config.getOrThrow<string>('MAIL_EXPEDITEUR');
  }

  // Au démarrage : on vérifie la connexion, sans empêcher l'application de démarrer
  async onModuleInit() {
    try {
      await this.transporteur.verify();
      console.log('[MailService] serveur SMTP joignable');
    } catch (e) {
      console.log('[MailService] serveur SMTP injoignable : ' + (e as Error).message);
    }
  }

  async envoyer(m: Message) {
    const info = await this.transporteur.sendMail({
      from: this.expediteur,
      to: m.a,
      subject: m.sujet,
      html: m.html,
      text: m.texte ?? m.html.replace(/<[^>]+>/g, ''),    // version texte pour les clients sans HTML
      attachments: m.piecesJointes,
    });
    return info.messageId as string;
  }
}
src/mail/mail.module.ts
import { Global, Module } from '@nestjs/common';
import { MailService } from './mail.service';

@Global()                       // utilisable dans tous les modules sans réimporter MailModule
@Module({ providers: [MailService], exports: [MailService] })
export class MailModule {}
src/mail/modeles.ts
// Échapper toute donnée venant de l'utilisateur avant de l'insérer dans du HTML
export const echapper = (s: string) =>
  s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]!);
src/app.module.ts
import { CacheModule } from '@nestjs/cache-manager';
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { EventEmitterModule } from '@nestjs/event-emitter';
import { ScheduleModule } from '@nestjs/schedule';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AuthModule } from './auth/auth.module';
import { DocumentsModule } from './documents/documents.module';
import { MailModule } from './mail/mail.module';
import { ScolariteModule } from './scolarite.module';
import { UtilisateursModule } from './utilisateurs/utilisateurs.module';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    TypeOrmModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        type: 'mysql',
        host: config.getOrThrow('DB_HOTE'),
        port: Number(config.get('DB_PORT', 3306)),
        username: config.getOrThrow('DB_UTILISATEUR'),
        password: config.get('DB_MOT_DE_PASSE', ''),
        database: config.getOrThrow('DB_NOM'),
        autoLoadEntities: true,
        synchronize: false,
      }),
    }),
    CacheModule.register({ isGlobal: true, ttl: 60_000 }),
    EventEmitterModule.forRoot(),
    ScheduleModule.forRoot(),
    MailModule,
    AuthModule,
    UtilisateursModule,
    ScolariteModule,
    DocumentsModule,
  ],
})
export class AppModule {}
Grille d'évaluation
CritèrePoints
Branche, commits clairs, stockage/ et .env non versionnés, .env.example à jour, étiquette v1.1.02
Entité et migration relue (sans lignes parasites), exécutée2
Dépôt : limite Multer, taille, type par signature, nom généré, fichier hors du dossier public4
Liste filtrée en SQL, téléchargement et suppression avec contrôle des droits, Content-Disposition4
Notification : événement, auditeur asynchrone, formateur du groupe, HTML échappé, panne SMTP sans effet sur le dépôt3
Statistiques en cache avec invalidation2
Tâches planifiées : expressions, fuseau, waitForCompletion, nettoyage correct2
Fichier .http, README, documentation Swagger du dépôt1
Total20

Cet article vous a-t-il aidé ?