EPIDOCS — Frontend¶

Description¶

EPIDOCS est un système de gestion documentaire pour les étudiants d'EPITECH Bénin. Le frontend fournit deux interfaces distinctes : un portail étudiant (demande de documents, suivi, réclamations) et un dashboard administrateur (gestion des modèles, génération de documents, maintenance système).

Repository : EpitechAfrik/epidocs-frontend
URL production : https://mydocs.epitools.bj
Port : 127.0.0.1:7012 (hôte) → 3000 (conteneur)
Registry : ghcr.io/epitechafrik/epidocs-frontend

Fonctionnalités principales¶

Portail étudiant¶

Demande de documents : certificats de scolarité, lettres de recommandation, etc.
Suivi de demande : timeline visuelle avec tracking par code unique
Réclamations : soumission et suivi des réclamations
Gestion de compte : sessions actives, demandes de modification d'informations
Notes d'information : téléchargement de PDFs publiés par l'administration
Annonces : bandeaux d'annonces ciblés par classe
Avatar généré : identicon dynamique (boring-avatars) affiché dans la navbar étudiant

Dashboard administrateur¶

Modèles de documents : upload, extraction d'attributs, activation/désactivation
Gestion des étudiants : recherche, suspension, migration entre classes, validation du statut diplômé (PGE3/PGE5)
Génération de documents : génération individuelle (wizard 3 étapes) et en lot par classe
Notes d'information : upload de PDFs ciblés par classe, activation/désactivation, suivi des téléchargements
Gestion des campus : création, édition, managers, templates par campus, champs personnalisés
Statistiques : tableau de bord avec métriques d'utilisation
Historique : consultation de l'historique documentaire par étudiant

Fonctionnalités superadmin¶

Mode maintenance : activation/désactivation avec redirection automatique des étudiants
Maintenance planifiée : programmation avec date de début/fin
Annonces : création et gestion de bandeaux d'information
Analytics : métriques détaillées par période
Logs d'audit : traçabilité des actions administratives, présentée en timeline lisible groupée par jour
Intégrations & clés API : gestion des comptes de service et des clés API pour les services externes (ex. Zeno)
Sauvegarde : export/import de la base de données

Architecture¶

Stack technique¶

Composant	Technologie	Version
Framework	Next.js (App Router)	16.1.0
Runtime	Node.js	20 (Alpine)
UI	React	19.0.0
Composants	Chakra UI	2.8.2
Styling	Tailwind CSS	3.4.1
HTTP	Axios	1.7.3
Formulaires	React Hook Form	7.62.0
Data fetching	TanStack React Query	5.90.21
Animations	Framer Motion	11.3.12
Avatars	boring-avatars	1.11.2
Gestionnaire de paquets	pnpm	10.18.3
Conteneur	Docker (node:20-alpine)	—

Structure des dossiers¶

src/
├── app/
│   ├── admin/                  # Dashboard administrateur
│   │   ├── components/         # Navbar, Sidebar
│   │   ├── admins/             # Gestion des admins
│   │   ├── analytics/          # Analytics (superadmin)
│   │   ├── announcements/      # Annonces (superadmin)
│   │   ├── audit-logs/         # Logs d'audit (superadmin)
│   │   ├── backup/             # Sauvegarde BDD (superadmin)
│   │   ├── batch-generate/     # Génération en lot
│   │   ├── campus/             # Gestion des campus
│   │   ├── dashboard/          # Statistiques
│   │   ├── documents/          # Historique documents
│   │   ├── generate-document/  # Génération unitaire
│   │   ├── info-notes/          # Notes d'information (PDFs)
│   │   ├── info-requests/      # Demandes de modification
│   │   ├── integrations/       # Comptes de service & clés API (superadmin)
│   │   ├── migration/          # Migration étudiants
│   │   ├── models/             # Modèles de documents
│   │   ├── pending/            # Étudiants en attente
│   │   ├── students/           # Gestion étudiants
│   │   ├── system-status/      # Maintenance (superadmin)
│   │   └── layout.js
│   │
│   ├── student/                # Portail étudiant
│   │   ├── components/         # Navbar, Profile, Banners
│   │   ├── historiques/        # Historique documents
│   │   ├── mes-demandes/       # Demandes de modification
│   │   ├── reclamations/       # Réclamations
│   │   ├── sessions/           # Gestion sessions
│   │   └── layout.js
│   │
│   ├── auth/                   # Authentification OAuth
│   ├── maintenance/            # Page maintenance
│   └── documents/tracking/     # Suivi public par code
│
├── services/                   # Couche API (Axios)
│   ├── axios.js                # Instance + intercepteurs
│   ├── auth/authServices.js    # Auth (login, logout, sessions)
│   ├── admin/adminServices.js  # Opérations admin
│   ├── admin/announcementService.js
│   ├── admin/infoNotesService.js
│   ├── admin/systemStatusService.js
│   ├── admin/integrationServices.js  # Comptes de service & clés API
│   │   (campus CRUD via adminServices.js)
│   └── students/index.js       # Opérations étudiant
│
├── context/                    # React Context
│   ├── userContext.js           # Auth + user state
│   └── sidebarContext.js        # Sidebar state
│
├── middlewares/                 # Helpers côté client
│   ├── protectedRoute.js       # Route protégée par droits
│   └── isAuthorizedShow.js     # Affichage conditionnel
│
├── components/
│   └── AppAvatar.js            # Avatar généré (boring-avatars)
├── utils/                      # Utilitaires (storage, dates)
├── constant/                   # Constantes (couleurs)
└── proxy.js                    # Middleware Next.js (auth guard)

Rôles et permissions¶

Droit	Superadmin	Admin	Étudiant
Gestion modèles	oui	oui	non
Génération unitaire	oui	oui	non
Génération en lot	oui	non	non
Notes d'information	oui	oui	téléchargement
Migration étudiants	oui	non	non
Gestion campus (édition/managers/templates)	oui	oui	non
Création/désactivation campus	oui	non	non
Mode maintenance	oui	non	non
Annonces	oui	non	non
Analytics / Audit	oui	non	non
Intégrations / clés API	oui	non	non
Sauvegarde BDD	oui	non	non
Demande de documents	non	non	oui
Réclamations	non	non	oui

Diagrammes¶

Architecture globale¶

graph TB
    User[Utilisateur / Navigateur]
    Nginx["Nginx<br/>Reverse proxy + TLS"]
    Frontend["Frontend Next.js<br/>:3000"]
    Backend["Backend Django<br/>API REST"]
    DB["Base de données"]
    Azure["Microsoft Azure AD<br/>(OAuth SSO)"]

    User --> Nginx
    Nginx --> Frontend
    Frontend --> Backend
    Backend --> DB
    Frontend --> Azure
    Backend --> Azure

Flux d'authentification¶

sequenceDiagram
    participant User as Utilisateur
    participant FE as Frontend Next.js
    participant Azure as Microsoft OAuth
    participant BE as Backend Django
    participant Cookie as Cookie auth_token

    User->>FE: Clic "Connexion Microsoft"
    FE->>Azure: Redirect OAuth
    Azure->>FE: Callback /auth/callback?code=XXX
    FE->>BE: POST /auth/sign_in {code, session_state}
    BE->>Azure: Validation du token
    BE->>Cookie: Set auth_token (HttpOnly)
    BE-->>FE: {user, role, rights}
    FE->>FE: Stockage user dans localStorage
    FE->>FE: Redirection selon rôle (admin/student)

Flux de génération de document¶

sequenceDiagram
    participant Admin as Admin (Frontend)
    participant API as Backend API
    participant PDF as Moteur PDF

    Admin->>API: GET /documents/available-document-types?studentEmail=xxx
    API-->>Admin: {documents: {allowed_documents: [...]}}

    Admin->>API: POST /documents/admin/generate-for-student<br/>{studentEmail, docId}
    API->>PDF: Génération du PDF
    PDF-->>API: Blob PDF
    API-->>Admin: Content-Type: application/pdf
    Admin->>Admin: Téléchargement automatique

Flux de génération en lot¶

sequenceDiagram
    participant Admin as Superadmin
    participant API as Backend API
    participant PDF as Moteur PDF

    Admin->>API: POST /documents/admin/batch-generate<br/>{classe: "PGE1", doc_id: "certificat_scolarite"}
    API->>PDF: Génération N PDFs
    PDF-->>API: ZIP contenant tous les PDFs
    API-->>Admin: Content-Type: application/zip<br/>X-Batch-Total: 45<br/>X-Batch-Generated: 43<br/>X-Batch-Errors: 2
    Admin->>Admin: Téléchargement ZIP + résumé

Flux des notes d'information¶

sequenceDiagram
    participant Admin as Admin (Frontend)
    participant API as Backend API
    participant Student as Étudiant (Frontend)

    Admin->>API: POST /documents/admin/info-notes<br/>(multipart: title, pdf_file, target_classes)
    API-->>Admin: {id, title, targetClasses, isActive}

    Student->>API: GET /documents/available-document-types
    API-->>Student: {documents: {...}, infoNotes: [{id, title, ...}]}

    Student->>API: GET /documents/info-notes/:id/download
    API-->>Student: Content-Type: application/pdf (blob)
    Student->>Student: Téléchargement automatique

Docker¶

Dockerfile¶

Image multi-stage basée sur node:20-alpine avec pnpm. Les variables NEXT_PUBLIC_* sont injectées au build via ARG.

Stage builder : installation des dépendances + build Next.js
Stage runner : copie du build optimisé, exécution en production

docker-compose.prod.yml¶

services:
  frontend:
    image: ghcr.io/epitechafrik/epidocs-frontend:latest
    container_name: epidocs_frontend_container
    restart: unless-stopped
    ports:
      - "127.0.0.1:7012:3000"
    env_file:
      - .env
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
      - NEXT_PUBLIC_WEB_URL=${NEXT_PUBLIC_WEB_URL}
    networks:
      - epidocs-network
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

networks:
  epidocs-network:
    driver: bridge

Points importants :

Le port est bindé sur 127.0.0.1 uniquement (accessible via Nginx seulement)
Le healthcheck utilise wget (pas de curl sur Alpine par défaut)
Logging limité à 30 Mo (3 fichiers de 10 Mo)
Réseau bridge dédié epidocs-network

Routes de l'application¶

Routes publiques (sans authentification)¶

Route	Description
`/auth`	Page de connexion Microsoft OAuth
`/auth/callback`	Callback OAuth
`/noaccount`	Page "aucun compte"
`/register`	Inscription étudiant en attente
`/desactivated`	Compte désactivé
`/documents/tracking/:id`	Suivi public d'un document
`/maintenance`	Page de maintenance
`/unauthorized`	Accès non autorisé

Routes admin (role: admin ou superadmin)¶

Route	Description
`/admin`	Dashboard principal
`/admin/models`	Gestion des modèles de documents
`/admin/students`	Gestion des étudiants
`/admin/pending`	Validation des inscriptions
`/admin/migration`	Migration de classe
`/admin/info-requests`	Demandes de modification
`/admin/dashboard`	Statistiques
`/admin/documents`	Historique documentaire
`/admin/admins`	Gestion des admins
`/admin/generate-document`	Génération unitaire
`/admin/batch-generate`	Génération en lot (superadmin)
`/admin/campus`	Gestion des campus
`/admin/info-notes`	Notes d'information (PDFs)
`/admin/system-status`	Mode maintenance (superadmin)
`/admin/announcements`	Annonces (superadmin)
`/admin/analytics`	Analytics (superadmin)
`/admin/audit-logs`	Logs d'audit (superadmin)
`/admin/integrations`	Comptes de service & clés API (superadmin)
`/admin/backup`	Sauvegarde BDD (superadmin)

Routes étudiant (role: student)¶

Route	Description
`/student`	Page principale + profil
`/student/historiques`	Historique des demandes
`/student/mes-demandes`	Demandes de modification
`/student/reclamations`	Réclamations
`/student/sessions`	Sessions actives

Fonctionnalités détaillées¶

Portail étudiant — redesign UI¶

Le portail étudiant a été entièrement redesigné (commit 2cfe100). Points notables :

Split-screen : profil à gauche, contenu principal à droite (layout existant conservé)
DocumentCard : refonte complète du composant de demande de document — meilleure hiérarchie visuelle, états de chargement, gestion des erreurs inline
Navbar : intègre désormais un AppAvatar (boring-avatars, variant beam) généré à partir du nom de l'utilisateur — pas d'image externe
Historique (/student/historiques) : les documents récents des classes précédentes sont clairement séparés des demandes actives
Modal de génération : stabilisée — les états de chargement et les erreurs sont correctement gérés sans rechargement intempestif

Migration et validation du statut diplômé (`/admin/migration`)¶

La page migration permet deux opérations distinctes sur une sélection d'étudiants :

1. Migration de classe¶

Déplace les étudiants sélectionnés vers une autre section (ex. PGE1 → PGE2) avec choix de l'année scolaire.

2. Validation du statut diplômé¶

Marque les étudiants PGE3 ou PGE5 comme diplômés. Une fois diplômé, l'étudiant voit une Attestation de scolarité à la place du Certificat de scolarité.

Raccourcis de sélection rapide

Des boutons "TEK3 (PGE3)" et "MSc Pro 2 (PGE5)" permettent de sélectionner tous les étudiants d'une section en une action (requête avec pageSize=9999).

Détection automatique des groupes

Lors de l'ouverture du modal, le frontend analyse la sélection et constitue deux groupes à partir du champ section de chaque étudiant. Si la sélection est mixte, le modal affiche le résumé par groupe :

12 étudiant(s) seront marqués diplômés en PGE3 (TEK 3)
 8 étudiant(s) seront marqués diplômés en PGE5 (MSc Pro 2)

Requêtes parallèles

Deux appels sont effectués en parallèle (Promise.all) — un par groupe — vers POST /student/admin/set-graduation-status/ avec le champ section approprié. Les résultats sont fusionnés et affichés dans une vue unifiée.

Colonne "Statut diplôme" dans le tableau

Badge vert PGE3 ✓ si PGE3Status === "success"
Badge vert PGE5 ✓ si PGE5Status === "success"
Tiret — si les deux statuts sont absents, vides ou null

Nommage des champs camelCase — deux endpoints différents

Les deux endpoints ne retournent pas les mêmes noms de champs :

GET /student/ (fiche étudiant) → pge3Status, pge5Status (tout en minuscules)
GET /student/admin/list/ (migration) → PGE3Status, PGE5Status (majuscules préservées)

Adapter le nom du champ selon l'endpoint utilisé dans le composant.

Reset

Un bouton reset (icône ✕, rouge) apparaît dès qu'un filtre ou une sélection est actif.

sequenceDiagram
    participant Admin as Admin (Frontend)
    participant API as Backend API

    Admin->>Admin: Clique "TEK3 (PGE3)"
    Admin->>API: GET /student/admin/list/?section=PGE3&pageSize=9999
    API-->>Admin: {results: [...tous les PGE3]}
    Admin->>Admin: Sélectionne tous les logins

    Admin->>Admin: Clique "Valider diplômé"
    Admin->>Admin: Groupe les logins par section (PGE3 / PGE5)

    par Appels parallèles
        Admin->>API: POST /student/admin/set-graduation-status/ {emails: [...], section: "PGE3"}
        Admin->>API: POST /student/admin/set-graduation-status/ {emails: [...], section: "PGE5"}
    end
    API-->>Admin: {updated, not_found_emails, wrong_section_emails}
    Admin->>Admin: Fusionne résultats et affiche le rapport

Gestion des campus (`/admin/campus`)¶

La page campus permet de gérer les établissements EPITECH rattachés à la plateforme.

Tableau de bord campus¶

Liste tous les campus avec : code, nom, ville, pays, directeur et statut (actif/inactif).

Créer un campus (superadmin uniquement)¶

Champs obligatoires : Code (ex. BEN) et Nom. Champs optionnels : ville, pays, adresse, téléphone, email, directeur (nom + titre FR/EN).

Drawer de détail — 3 onglets¶

Onglet Infos

Formulaire d'édition des informations du campus
Champs personnalisés (extraFields) : paires clé/valeur libres utilisables dans les templates .docx via {{campus_extra_<clé>}} (ex. {{campus_extra_ape}})
Bouton "Désactiver" (superadmin uniquement, action réversible)

Onglet Managers

Assigne des admins existants comme managers d'un campus. Un manager est un admin avec responsabilité spécifique sur ce campus.

Onglet Templates

Permet d'uploader des overrides de templates par campus : si un template campus existe pour un type de document, il est utilisé à la place du template global. Supporte les modèles FR et EN (.docx).

sequenceDiagram
    participant Admin as Admin (Frontend)
    participant API as Backend API

    Admin->>API: GET /campus/
    API-->>Admin: [{id, code, name, city, isActive, ...}]

    Admin->>Admin: Clique sur un campus
    par Chargement parallèle
        Admin->>API: GET /campus/:id/managers/
        Admin->>API: GET /campus/:id/templates/
        Admin->>API: GET /admin/admins/?limit=100
    end
    API-->>Admin: managers, templates, admins

    Admin->>API: POST /campus/:id/templates/ (multipart: document_type, modele, modele_en)
    API-->>Admin: template créé/mis à jour

Nommage camelCase vs snake_case

L'API campus retourne du camelCase (directorName, isActive, extraFields). Le service frontend normalise automatiquement — ne pas utiliser snake_case pour ces champs.

Intégrations & clés API (`/admin/integrations`)¶

Écran réservé aux superadmins permettant de gérer les comptes de service et les clés API utilisés par les services externes (ex. Zeno) pour s'authentifier auprès d'EPIDOCS sans session/cookie. L'entrée du menu est masquée pour les non-superadmins, et la page applique un garde de rôle (403 côté API).

Base des routes : <API>/integrations/v1 (JSON camelCase, session admin via cookie JWT). Service frontend : src/services/admin/integrationServices.js.

Comptes de service¶

Liste des comptes avec leur statut (actif/inactif), le nombre de clés actives et une sous-liste dépliable des clés (préfixe, statut, dernière utilisation). Actions disponibles :

Créer un compte (génère automatiquement une 1ʳᵉ clé)
Renommer / éditer (nom, description, statut actif)
Activer / désactiver — désactiver coupe immédiatement l'accès de toutes les clés du compte
Supprimer (irréversible — supprime le compte et toutes ses clés, avec confirmation)

Clés API¶

Pour chaque clé : émettre une nouvelle clé, régénérer (rotate) — révoque l'ancienne et en émet une nouvelle —, ou révoquer (confirmation, coupe l'accès immédiatement).

La clé brute n'est affichée qu'une seule fois

La clé en clair (apiKey) n'est renvoyée que par les réponses de création de compte, émission de clé et rotation. Le backend ne stocke que le hash, et les GET ne renvoient jamais la clé brute (seulement le prefix — 8 premiers caractères — pour l'identifier).

Après ces 3 actions, le frontend affiche la clé dans une modale « Copier » avec l'avertissement « Cette clé ne sera plus jamais affichée ». La fermeture sur l'overlay est désactivée pour éviter une perte accidentelle.

Bouton / action UI	Appel
Charger l'écran	`GET /integrations/v1/admin/service-accounts`
Nouveau service	`POST /integrations/v1/admin/service-accounts` → modale clé
Activer / Désactiver / Renommer	`PATCH /integrations/v1/admin/service-accounts/{id}`
Supprimer le service	`DELETE /integrations/v1/admin/service-accounts/{id}`
Générer une clé	`POST /integrations/v1/admin/service-accounts/{id}/keys` → modale clé
Régénérer (rotate)	`POST /integrations/v1/admin/keys/{keyId}/rotate` → modale clé
Révoquer	`POST /integrations/v1/admin/keys/{keyId}/revoke`

Logs d'audit (`/admin/audit-logs`)¶

Écran réservé aux superadmins retraçant toutes les actions sur la plateforme. L'affichage est une timeline lisible groupée par jour (et non un tableau de données brutes) :

Humanisation des valeurs : chaque action a un libellé FR, une couleur et une icône ; les actions non mappées (snake_case) sont converties automatiquement en texte lisible. Les rôles et les cibles (type / id → « Étudiant #12 ») sont également formatés.
Phrase lisible par entrée : email de l'acteur + badge de rôle, puis « a généré un document · Étudiant #12 ».
Temps relatif (« il y a 2 h ») avec la date complète au survol ; entrées regroupées sous des en-têtes « Aujourd'hui » / « Hier » / date complète.
Vue détail : un clic sur une entrée ouvre un drawer latéral avec tous les champs formatés (utilisateur, rôle, cible, date absolue + relative, IP, identifiant, et un bloc JSON details/metadata si l'API en renvoie).
Filtres : recherche par email d'acteur (avec debounce) et sélection par type d'action ; pagination (25 par page).

Fiche étudiant (`/admin/students`)¶

Le panneau de détail affiche toujours le champ Statut diplôme (endpoint /student/ → pge3Status) :

Badge PGE3 diplômé ✓ si pge3Status === "success"
Badge PGE5 diplômé ✓ si pge5Status === "success"
Tiret — si aucun diplôme validé

Page modèles (`/admin/models`)¶

Spinner de chargement initial pendant la récupération des modèles, évitant le flash "Aucun document trouvé".

Intercepteurs Axios¶

L'instance Axios (src/services/axios.js) gère automatiquement :

Requêtes : Content-Type: application/json par défaut, withCredentials: true
Erreur 401 : redirection vers /auth (sauf si déjà sur la page auth)
Erreur 503 : mode maintenance — redirige les étudiants vers /maintenance, les admins/superadmins ne sont pas redirigés

Variables d'environnement¶

Variable	Description	Exemple
`NEXT_PUBLIC_WEB_URL`	URL publique du frontend	`https://mydocs.epitools.bj`
`NEXT_PUBLIC_API_URL`	URL publique du backend API	`https://api-mydocs.epitools.bj`
`NODE_ENV`	Mode d'exécution	`production`

Variables NEXT_PUBLIC_*

Les variables préfixées par NEXT_PUBLIC_ sont exposées au navigateur. Ne jamais y mettre de secrets. Ces variables sont injectées au build time (pas au runtime), donc un changement nécessite un rebuild de l'image Docker.

Pipeline CI/CD¶

Déclencheurs¶

Push sur main ou develop
Pull request vers main
Dispatch manuel

Jobs¶

graph LR
    CI["CI<br/>Lint + Build"] --> Docker["Build Docker<br/>Push GHCR"]
    Docker --> Deploy["Déploiement<br/>SCP + SSH"]
    Deploy --> Health["Health Check"]

CI : checkout → setup pnpm → install → lint → build → upload artifact
Build Docker : build image multi-stage → push ghcr.io/epitechafrik/epidocs-frontend:latest
Deploy : SCP du docker-compose.prod.yml + .env → SSH pour pull et restart conteneur
Health check : vérification que le conteneur répond sur le port 3000

Secrets GitHub nécessaires¶

Secret	Description
`NEXT_PUBLIC_API_URL`	URL du backend
`NEXT_PUBLIC_WEB_URL`	URL du frontend
`SSH_PRIVATE_KEY`	Clé SSH pour accès au VPS
`VPS_IP`	Adresse IP du VPS
`VPS_USER`	Utilisateur SSH (`root`)
`ENV_FILE`	Contenu complet du fichier `.env`
`GITHUB_TOKEN`	Token GHCR (auto-fourni)

Rollback¶

Procédure¶

# 1. Lister les images disponibles
docker images ghcr.io/epitechafrik/epidocs-frontend --format "table {{.Tag}}\t{{.CreatedAt}}"

# 2. Modifier le tag dans docker-compose.prod.yml
#    image: ghcr.io/epitechafrik/epidocs-frontend:sha-XXXXXXX

# 3. Redéployer
cd /root/projects/epidocs/epidocs-frontend
docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d

# 4. Vérifier
docker ps | grep epidocs_frontend
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:7012

Après le rollback¶

Investiguer la cause sur main
Pousser un correctif
Le pipeline redéploiera automatiquement