EPIDOCS — Backend¶

Description¶

Le backend EPIDOCS est une API REST développée en Django (Django REST Framework) qui gère l'authentification Microsoft OAuth, la génération de documents PDF, la gestion des étudiants et les fonctionnalités d'administration.

Repository : EpitechAfrik/epidocs-backend
URL production : https://api.mydocs.epitools.bj
Port : 127.0.0.1:7010 (hôte) → port interne conteneur

Stack technique¶

Composant	Technologie
Framework	Django + Django REST Framework
Sérialisation	djangorestframework-camel-case (snake_case → camelCase)
Authentification	Microsoft Azure AD (OAuth 2.0) + JWT (HttpOnly cookie)
Génération PDF	Moteur de templates PDF interne
Base de données	PostgreSQL (ou SQLite en dev)
Conteneur	Docker

Sérialisation camelCase

Le backend utilise djangorestframework-camel-case : il accepte les requêtes en snake_case et retourne les réponses en camelCase. Le frontend doit gérer les deux formats dans certains cas (voir normalizeStatusData() côté frontend).

Routes API principales¶

Authentification¶

Méthode	Route	Description
POST	`/auth/sign_in`	Login OAuth (code + session_state)
POST	`/auth/logout`	Déconnexion
GET	`/auth/me`	Informations utilisateur + droits
GET	`/auth/student/me`	Informations étudiant
GET	`/auth/sessions`	Sessions actives
DELETE	`/auth/sessions/:id`	Révoquer une session
DELETE	`/auth/sessions/others`	Révoquer toutes les autres sessions

Documents¶

Méthode	Route	Description
GET	`/documents/`	Liste des modèles uploadés
POST	`/documents/`	Créer un nouveau modèle
GET	`/documents/:id`	Détail d'un modèle
PATCH	`/documents/:id`	Modifier un modèle (visibilité, fichier)
GET	`/documents/document-type-choices`	Types de documents disponibles
GET	`/documents/available-document-types`	Documents autorisés pour un étudiant/classe
GET	`/documents/available-attributes`	Attributs de document disponibles
POST	`/documents/extract-attributes`	Extraire les attributs d'un fichier
GET	`/documents/download/student-template`	Télécharger le template étudiant
GET	`/documents/download/english-score-template`	Télécharger le template scores anglais
GET	`/documents/download/readme`	Télécharger le README

Documents — Admin¶

Méthode	Route	Description
POST	`/documents/admin/generate-for-student`	Générer un PDF pour un étudiant
POST	`/documents/admin/batch-generate`	Générer en lot (ZIP) pour une classe
GET	`/documents/admin/student-history/:email/`	Historique documentaire d'un étudiant
DELETE	`/documents/admin/delete-document/:trackingCode/`	Supprimer un document
GET	`/documents/admin/dashboard/stats/`	Statistiques du dashboard

Documents — Overrides par classe¶

Nouveau modèle ClassDocumentType : un type de document peut avoir un template spécifique par classe (PGE1…PGE5, PSO, CodingAcademy), en plus des overrides existants par campus. Voir frontend.md — Overrides de templates par classe pour l'ordre de résolution (campus > classe > global) et l'UI (/admin/models, onglet « Overrides classe »).

Méthode	Route	Description
GET	`/documents/admin/classes/<classe>/templates`	Liste les overrides de templates d'une classe
POST	`/documents/admin/classes/<classe>/templates`	Crée ou met à jour un override (multipart : `document_type` = `doc_id` du type de document, ex. `lettre_recommandation` ; `modele` et/ou `modele_en` = fichiers `.docx`, indépendamment optionnels)
DELETE	`/documents/admin/classes/<classe>/templates/<doc_id>`	Supprime l'override d'une classe pour ce type de document

Gated par le droit can_manage_document_types (création/suppression uniquement ; la lecture reste ouverte à tout admin).

Notes d'information¶

Méthode	Route	Description
GET	`/documents/admin/info-notes`	Liste des notes (admin, filtre `?classe=`)
POST	`/documents/admin/info-notes`	Créer une note (multipart/form-data)
PUT	`/documents/admin/info-notes/:id`	Modifier une note (multipart/form-data)
PATCH	`/documents/admin/info-notes/:id/toggle`	Activer/désactiver une note
DELETE	`/documents/admin/info-notes/:id`	Supprimer une note
GET	`/documents/info-notes/:id/download`	Télécharger le PDF (étudiant)

Étudiants¶

Méthode	Route	Description
GET	`/students`	Liste des étudiants (paginée, recherche)
PUT	`/students/suspend`	Suspendre/réactiver un étudiant
GET	`/student/admin/list/`	Liste pour migration (filtres section, année)
POST	`/student/migrate-students/`	Migrer des étudiants
GET	`/student/admin/info-change-requests/`	Demandes de modification
POST	`/student/admin/review-info-change-requests/`	Valider/refuser des demandes

Utilisateurs (admins)¶

Méthode	Route	Description
GET	`/users/list`	Liste des admins
POST	`/users`	Créer un admin
PUT	`/users`	Modifier un admin
DELETE	`/users`	Supprimer un admin
GET	`/admin/rights`	Nouveau (2026-09-09) — catalogue dynamique des droits (`[{value, label, description, group}]`), consommé par `/admin/admins` au lieu d'une liste hardcodée. Voir frontend.md

Étudiants — édition directe et intégrité des données¶

Méthode	Route	Description
PATCH	`/student/admin/<login>/edit`	Nouveau (2026-09-09) — édition directe d'une info étudiant par un admin (typo, sans passer par une demande) ; renvoie `generatedDocumentsCount`. Voir frontend.md
GET	`/admin/data-checks`	Nouveau (2026-09-09) — liste tous les checks d'intégrité de données avec leur compte d'anomalies
GET	`/admin/data-checks/<check_id>`	Détail paginé des enregistrements concernés par un check (`?page=&limit=`)
POST	`/admin/data-checks/<check_id>/fix`	Corrige un check (body optionnel `{"ids": [...]}`, sinon corrige tout)

Détail du framework DataCheck (registre backend, comment ajouter un nouveau check) : docs/epidocs-api/operations-manuelles.md §4 de ce même site. Frontend : frontend.md.

Présence Campus (Attendance)¶

Module entièrement documenté à part — routes, droits, modèle de données : epidocs-api/attendance.md. Ce que le frontend en consomme et comment : epidocs-frontend/attendance.md.

Système (superadmin)¶

Méthode	Route	Description
GET	`/admin/system-status`	Statut du système (maintenance)
PUT	`/admin/system-status`	Activer/désactiver la maintenance
GET	`/admin/analytics`	Analytics par période
GET	`/admin/audit-logs`	Logs d'audit
GET	`/admin/backup/export`	Export base de données
POST	`/admin/backup/import`	Import base de données

Annonces¶

Méthode	Route	Description
GET	`/admin/announcements/public`	Annonces publiques (pas d'auth)
GET	`/admin/announcements`	Toutes les annonces (admin)
POST	`/admin/announcements`	Créer une annonce
PUT	`/admin/announcements/:id`	Modifier une annonce
DELETE	`/admin/announcements/:id`	Supprimer une annonce

Query params notables¶

`GET /documents/available-document-types`¶

Param	Description	Exemple
`studentEmail`	Email de l'étudiant (admin)	`?studentEmail=prenom.nom@epitech.eu`
`classe`	Code de la classe (batch)	`?classe=PGE1`
(aucun)	Utilise la section de l'utilisateur connecté (étudiant)	—

Réponse type¶

{
  "documents": {
    "id": "PGE4",
    "name": "MSc Pro 1",
    "cycle": "Master Pro",
    "allowed_documents": [
      {
        "id": "certificat_scolarite",
        "name": "Certificat de scolarité",
        "description": "Atteste que l'étudiant est inscrit..."
      }
    ],
    "english_documents": []
  }
}

Modèle de données simplifié¶

Student
├── login (email), nom, prenom, civilite
├── dateNaissance, promo, section, annee
├── accountSuspended (boolean)
└── english_score, credit

Section (classe)
├── id (PGE1, PGE2, PGE3, PGE4, PGE5, PSO, CodingAcademy)
├── name, cycle, common_name
├── credit, credit_to_pass
├── allowed_documents[]
└── english_documents[]

Document (modèle/template)
├── id, name, description
├── file (fichier template)
├── attributes[] (champs dynamiques)
└── is_active (boolean)

InfoNote
├── id, title, description
├── pdf_file (fichier PDF uploadé)
├── target_classes[] (PGE1, PGE2, etc.)
├── is_active (boolean)
├── download_count (integer)
├── created_by (email admin)
└── created_at, updated_at

Announcement
├── id, title, message
├── type (info, warning, danger)
├── target (students, admins, all)
├── target_class (optionnel)
├── start_date, end_date
└── is_active (boolean)

Cookies d'authentification¶

Cookie	Type	Description
`auth_token`	HttpOnly	JWT d'authentification — non accessible en JS

Cookie Domain en développement

En dev local, le backend Django doit configurer AUTH_COOKIE_DOMAIN = None pour éviter le blocage du Set-Cookie par le navigateur. En production, utiliser le domaine racine (ex: .epitools.bj).

Maintenance mode¶

Le backend intercepte toutes les requêtes et retourne une erreur 503 quand le système est en maintenance :

{
  "is_active": false,
  "reason": "Maintenance planifiée",
  "updated_at": "2026-02-22T10:00:00Z"
}

Routes exemptées

Les routes d'authentification (/auth/sign_in, /auth/callback) doivent être exemptées du middleware de maintenance pour permettre aux admins de se connecter et désactiver la maintenance.