🔵 Cahier des charges

[ebouchut]

Cahier des charges

Note

Cette issue contient le cahier des charges.

• Les éléments qui ont été entériné sont annotés avec (acté) (authentification, gestion des utilisateurs/rôles, audit).
• Les éléments marqués (proposé) sont une proposition à valider/affiner.
• L'évaluation automatique de code est reportée après la v1.0.

1. Contexte

Learn-dev est une plateforme Web d'apprentissage interactif de la
programmation, fondée sur la pratique et le retour d'information.
C'est mon projet de fin d'étude pour la certification Développeur Web et Web Mobile
(DWWM) à La Plateforme_.

2. Objectifs

• Offrir un environnement interactif pour apprendre des concepts de programmation.
• Permettre une pratique concrète (exercices, leçons).
• Gérer plusieurs rôles d'utilisateurs (Étudiant, Formateur, Administrateur).
• Démontrer une maîtrise du développement full-stack aux standards de l'industrie.

3. Périmètre

Dans le périmètre (v1.0)

• Authentification par session serveur (inscription, connexion, déconnexion).
• Vérification d'adresse e-mail et réinitialisation de mot de passe par e-mail.
• Gestion des utilisateurs, des rôles et de leurs associations.
• Journal d'audit de sécurité.
• Socle du domaine pédagogique (proposé) (Cf. 5.2).

Hors du périmètre / évolutions futures

• Évaluation automatique de code (exécution + notation) (reportée après la v1.0).
• Microservice d'exécution de code en bac à sable (runner) (voir ADR-0002).
• Application mobile / API publique tierce.

4. Acteurs (personas)

Acteur	Description	Droits principaux
Visiteur	Non authentifié	Consulter les pages publiques, s'inscrire, se connecter
Étudiant	Apprenant inscrit	Suivre des cours, réaliser des exercices, suivre sa progression
Formateur	Auteur de contenu	Créer/éditer des cours, des leçons et des exercices (proposé)
Administrateur	Gestion de la plateforme	Gérer des utilisateurs et des rôles, consulter l'audit

5. Exigences fonctionnelles

Note

EF est l'abréviation d'une exigence fonctionnelle.

5.1 Authentification et comptes (établi)

• EF-1 Inscription d'un compte (nom d'utilisateur, e-mail, mot de passe).
• EF-2 Vérification de l'adresse e-mail via un lien à usage unique et expirant.
• EF-3 Connexion / déconnexion par session serveur (cookie HttpOnly, Secure, SameSite).
• EF-4 Réinitialisation du mot de passe (mot de passe oublié) par e-mail (utilisation d'un jeton aléatoire opaque, haché, à usage unique et expirant, voir issue 🟢 feat(auth) – Password reset flow (forgot password) #51).
• EF-5 Verrouillage de compte après N échecs de connexion ; suivi des tentatives.
• EF-6 Gestion du profil utilisateur (consultation, mise à jour).

5.2 Domaine pédagogique (proposé)

• EF-7 (proposé) Cours : un cours regroupe des leçons ordonnées.
• EF-8 (proposé) Leçon : contenu pédagogique (texte, extraits de code, médias).
• EF-9 (proposé) Exercice : énoncé associé à une leçon.
• EF-10 (proposé) Inscription d'un étudiant à un cours (enrollment).
• EF-11 (proposé) Progression : suivi de l'avancement (leçons/exercices terminés).
• EF-12 (proposé) Création de contenu par le formateur (cours, leçons, exercices).
• EF-13 (futur) Soumission de code et évaluation automatique (reportée, voir §2).

5.3 Administration & sécurité (établi)

• EF-14 Gestion des rôles et de leur attribution aux utilisateurs.
• EF-15 Journalisation d'audit des actions sensibles (connexion, réinitialisation, modifications).
• EF-16 Contrôle d'accès basé sur les rôles (RBAC) sur l'ensemble des fonctionnalités.

6. Exigences non fonctionnelles

Note

ENF est l'abréviation d'une exigence non fonctionnelle.

• ENF-1 Sécurité : conformité OWASP ; hachage des mots de passe (bcrypt/argon2) ;
  protection CSRF (intégrée à Spring Security/Thymeleaf) ; validation des entrées ;
  identifiants user_id non énumérables (UUID, voir ADR-0003).
• ENF-2 Conformité RGPD : données personnelles minimales, droit à l'effacement,
  consentement, traçabilité (audit).
• ENF-3 Performance : temps de réponse raisonnable des pages (objectif < 500 ms en local).
• ENF-4 Accessibilité : viser WCAG 2.1 AA.
• ENF-5 Internationalisation : interface en français (et anglais en option).
• ENF-6 Maintenabilité : tests automatisés, intégration continue, migrations versionnées (Liquibase).
• ENF-7 Portabilité : exécution via conteneurs (Podman/Docker Compose).
• ENF-8 Disponibilité & données : sauvegardes de la base, stratégie de restauration.

7. Contraintes techniques

• Backend : Java 21, Spring Boot 3.x, Spring Security, Thymeleaf (rendu côté serveur).
• Bases de données : PostgreSQL 17 (cœur relationnel), MongoDB 8 (le cas échéant).
• Persistance/migrations : Liquibase (changesets SQL formatés, append-only).
• Build : Maven ; Conteneurisation : Podman / Docker Compose.
• Architecture : monorepo ; authentification par session (pas de JWT côté web (ADR-0001).
• Modèle de données : documenté en Merise (MCD/MLD/MPD) et en ERD (Cf. CONTRIBUTING.md).

8. Modèle de données

Le modèle de données est décrit dans CONTRIBUTING.md (sections MCD, MLD, MPD, ERD).
Entités actuelles : users, roles, user_roles (table de jonction),
email_tokens, reset_tokens, audit_logs.
Le domaine pédagogique (proposé) ajoutera des entités telles que courses,
lessons, (exercises, enrollments, progress).

9. Décisions d'architecture (ADR)

Les décisions structurantes sont consignées dans docs/adr/ (format MADR) :

• ADR-0001 Sessions serveur plutôt que JWT (authentification web).
• ADR-0002 Authentification inter-services par jeton de service (proposé).
• ADR-0003 Clé primaire UUID pour users, BIGINT ailleurs.
• ADR-0004 Mailpit comme collecteur SMTP local.

Cf. #63

10. Livrables

• Projet:
  • Code source (backend + frontend Thymeleaf) dans le monorepo.
  • Schéma de base de données versionné (Liquibase), diagrammes Merise (MCD, MLD, MPD) et ERD.
  • Documentation (README.md, CONTRIBUTING.md, ADR).
  • Tests automatisés + intégration continue.
• Documents:
  • Dossier Professionnel
  • Dossier Projet
  • Diaporama de présentation du projet

11. Critères d'acceptation (vue d'ensemble)

• Un visiteur peut s'inscrire, vérifier son e-mail, se connecter et se déconnecter.
• Un utilisateur peut réinitialiser son mot de passe par e-mail (🟢 feat(auth) – Password reset flow (forgot password) #51).
• Le contrôle d'accès par rôle est appliqué à toutes les fonctionnalités sensibles.
• Les actions sensibles sont journalisées dans l'audit.
• (proposé) Un étudiant peut s'inscrire à un cours et suivre des leçons/exercices.
• (proposé) Un formateur peut créer et éditer du contenu pédagogique.