transfer from private server/git server

docs/03_cahier_des_charges.md

@@ -0,0 +1,185 @@
+# Sections 1 à 20 — Cahier des charges GestHub
+
+## Section 1 — Présentation du projet
+
+GestHub est une application web intranet/extranet multi-services destinée à
+centraliser les outils utilisés au quotidien pendant la formation à Ynov
+Bordeaux Campus (spécialité Robotique & Systèmes Embarqués) : annonces,
+partage de fichiers, planning, chat et Kanban, le tout derrière une
+authentification unique (SSO). Projet personnel auto-initié, démarré pendant
+les ydays de B2 (avril 2025) et poursuivi jusqu'à ce jour.
+
+## Section 2 — Contexte et origine
+
+Avant GestHub, la coordination reposait sur des outils disparates :
+WhatsApp pour les annonces (aucune permanence de l'information), clés USB
+ou liens temporaires pour les fichiers (aucun contrôle d'accès), agendas
+séparés pour le planning (aucune vision collective). Ce constat personnel a
+motivé la création d'un outil unique et centralisé.
+
+## Section 3 — Objectifs du projet
+
+- Centraliser les annonces, fichiers, planning et communication dans un seul
+  point d'entrée authentifié.
+- Garantir la persistance et la traçabilité de l'information (contrairement
+  aux outils volatils utilisés auparavant).
+- Construire une infrastructure reproductible (Infrastructure as Code) et
+  déployable en moins de 5 minutes sur une machine Linux vierge.
+- Servir de support d'apprentissage et de preuve de compétence pour le titre
+  RNCP 36463 (CDAN).
+
+## Section 4 — Analyse de l'existant
+
+| Besoin | Outil utilisé avant GestHub | Limite constatée |
+|---|---|---|
+| Annonces | WhatsApp | Pas d'historique structuré, pas de droits |
+| Fichiers | Clés USB / liens temporaires | Aucun contrôle d'accès, pas de traçabilité |
+| Planning | Agendas personnels | Pas de vision collective |
+| Chat | Discord / groupes épars | Fragmentation, pas de SSO |
+| Authentification | Comptes séparés par outil | Pas d'identité unique |
+
+## Section 5 — Parties prenantes et public visé
+
+- **Utilisateur standard** : consulte les annonces, le planning, télécharge
+  ses fichiers, participe au chat.
+- **Administrateur** (groupe Keycloak `/admin`) : publie/modifie/supprime
+  les annonces et événements, gère la disposition du tableau de bord,
+  supprime tout fichier.
+- **Public secondaire** : intervenants et évaluateurs des revues de projet
+  ydays, jury de certification RNCP.
+
+## Section 6 — Besoins par profil utilisateur
+
+| Profil | Besoin principal |
+|---|---|
+| Standard | Voir les annonces et le planning, gérer ses propres fichiers, accéder au chat |
+| Admin | Tout ce que fait un standard, + publier/gérer les annonces, événements et widgets |
+| (Super-admin envisagé) | Administration Keycloak elle-même (hors périmètre applicatif GestHub) |
+
+## Section 7 — Acteurs et rôles
+
+Les rôles sont portés par les **groupes Keycloak**, propagés dans le token
+OIDC (claim `groups`) et vérifiés à chaque requête sensible côté Flask
+(`services/auth_service.py`) — aucune notion de rôle n'est stockée
+localement en dehors de la session applicative.
+
+## Section 8 — Périmètre fonctionnel (10 modules)
+
+| # | Module | Statut | Technologies |
+|---|---|---|---|
+| 1 | Authentification SSO | Terminé | Keycloak, OIDC, Authlib |
+| 2 | Tableau de bord / widgets | Terminé | Flask, PyMySQL, SortableJS |
+| 3 | Annonces | Terminé | Flask, PyMySQL, MariaDB |
+| 4 | Partage de fichiers | Terminé | Flask, python-magic, PyMySQL |
+| 5 | Planning / événements | Terminé | Flask, PyMySQL |
+| 6 | Chat | Terminé (réutilisation) | Mattermost (iframe, SSO partagé) |
+| 7 | Kanban | Terminé (réutilisation) | Mattermost Boards (iframe) |
+| 8 | Gestion des droits | Terminé | Groupes Keycloak, décorateurs Flask |
+| 9 | Journalisation / audit | Terminé | Table `audit_log`, MariaDB |
+| 10 | Infrastructure | Terminé | Docker Compose, Caddy, TLS auto |
+
+## Section 9 — Exigences fonctionnelles (EXF)
+
+| ID | Exigence | Priorité | Critère d'acceptation |
+|---|---|---|---|
+| EXF-01 | Authentification SSO Keycloak | HAUTE | Connexion redirige vers Keycloak et revient avec une session valide |
+| EXF-02 | Rôles admin/standard | HAUTE | Une route admin renvoie 403 pour un utilisateur sans groupe `/admin` |
+| EXF-03 | CRUD Annonces | HAUTE | Un admin peut créer/modifier/supprimer une annonce, visible par tous |
+| EXF-04 | Épinglage des annonces | MOYENNE | Une annonce épinglée apparaît en tête de liste |
+| EXF-05 | Upload de fichier validé | HAUTE | Un fichier hors liste blanche (type/extension/taille) est rejeté (400) |
+| EXF-06 | Téléchargement sécurisé | HAUTE | Le téléchargement d'un fichier d'autrui par un non-admin renvoie 403 |
+| EXF-07 | Suppression de fichier | MOYENNE | Le propriétaire ou un admin peut supprimer, les autres sont refusés |
+| EXF-08 | Listing des fichiers | MOYENNE | La liste renvoie les métadonnées (nom, taille, date) sans exposer le chemin disque |
+| EXF-09 | Création d'événements | MOYENNE | Un admin peut créer un événement avec dates de début/fin cohérentes |
+| EXF-10 | Suppression d'événements | BASSE | Un admin peut supprimer un événement existant |
+| EXF-11 | Tableau de bord personnalisable | MOYENNE | Un admin peut ajouter/déplacer/supprimer un widget, persisté en base |
+| EXF-12 | Intégration Chat/Kanban | HAUTE | Les widgets iframe Mattermost s'affichent avec authentification partagée |
+
+## Section 10 — Architecture générale (1/2 — logique)
+
+Voir Bloc 1 — C3 (« Concevoir une architecture fiable ») pour le détail :
+architecture en 5 couches (présentation, contrôleur, service, accès
+données, infrastructure), séparation stricte des responsabilités.
+
+## Section 11 — Contraintes de sécurité
+
+Voir tableau OWASP Top 10 détaillé (Partie 4 — Grille de recette et
+risques). Contraintes principales : secrets hors code source (.env),
+requêtes paramétrées systématiques, réseau Docker interne, vérification de
+rôle à chaque route sensible, aucune fuite d'information dans les réponses
+d'erreur.
+
+## Section 12 — Architecture générale (2/2 — infrastructure)
+
+Architecture 3 tiers : **Caddy** (présentation/proxy, seul point
+d'exposition publique), **Flask** (métier/applicatif), **MariaDB +
+Keycloak** (données/identité). Chaque service est isolé dans un conteneur
+Docker sur le réseau interne `gesthub-net`.
+
+## Section 13 — Modèle de données
+
+5 tables en 3ème forme normale (voir `web/init.sql`) : `annonces`,
+`fichiers`, `evenements`, `blocks`, `audit_log`. Aucune duplication des
+données d'identité — la référence utilisateur se fait uniquement via le
+`sub` OIDC (chaîne opaque fournie par Keycloak).
+
+## Section 14 — Exigences non fonctionnelles (EXNF)
+
+| ID | Exigence | Vérification |
+|---|---|---|
+| EXNF-01 | Aucune injection SQL possible | Test TS-01 (requêtes paramétrées) |
+| EXNF-02 | Secrets hors code source | `.env` + `.gitignore`, `config.py` lit `os.environ` |
+| EXNF-03 | Disponibilité du service | `restart: unless-stopped`, healthcheck MariaDB |
+| EXNF-04 | Tenue en charge | Gunicorn 4 workers (formule 2×CPU+1) |
+| EXNF-05 | Accessibilité de base (RGAA) | Attributs alt/aria-label, HTML sémantique |
+| EXNF-06 | Traçabilité des actions sensibles | Table `audit_log`, alimentée par tous les services |
+| EXNF-07 | Portabilité | 100 % conteneurisé, `docker compose up -d` |
+| EXNF-08 | Maintenabilité | Architecture en couches, Repository Pattern |
+| EXNF-09 | Qualité du code | flake8 : 0 violation (preuve réelle, Annexe A1) |
+| EXNF-10 | Testabilité | 34 tests automatisés exécutés avec succès (Annexe A1 / Partie 4) |
+
+## Section 15 — Contraintes techniques et choix technologiques
+
+Python/Flask (maîtrisé depuis B1/B2 Ynov), MariaDB (SGBDR open source,
+compatible InnoDB/ACID), Keycloak (SSO open source, supporte OIDC standard),
+Docker (portabilité), Caddy (TLS automatique sans configuration manuelle de
+certificats — gain de temps pour un projet solo).
+
+## Section 16 — Planning prévisionnel
+
+Voir document dédié (Section 16 détaillée — Partie « Planning prévisionnel »).
+
+## Section 17 — Gestion des risques projet
+
+| Risque | Impact | Mitigation |
+|---|---|---|
+| Interruption longue du projet (indisponibilité) | Perte de contexte | Journal de bord, README à jour, code auto-documenté |
+| Dépendance à un service externe (Mattermost) | Fonctionnalité chat/Kanban indisponible | Service isolé, redémarrage indépendant (Docker) |
+| Erreur de configuration Keycloak | Blocage de l'authentification | Export de la configuration réalm (`export_keycloak/`) |
+| Régression lors d'une évolution | Fonctionnalité cassée silencieusement | Suite de tests automatisés (34 cas), exécutée avant chaque livraison |
+
+## Section 18 — Critères d'acceptation / recette
+
+Voir Partie 4 — Grille de recette (15 critères).
+
+## Section 19 — Glossaire
+
+- **OIDC** : OpenID Connect, protocole d'authentification basé sur OAuth2.
+- **SSO** : Single Sign-On, authentification unique pour plusieurs services.
+- **sub** : identifiant unique et opaque d'un utilisateur dans un token OIDC.
+- **3NF** : troisième forme normale (modélisation de bases de données
+  relationnelles).
+- **Repository Pattern** : patron de conception isolant l'accès aux données
+  derrière une interface stable.
+
+## Section 20 — Annexes
+
+Voir Annexe A1 (Qualité du code), Annexe A2 (Estimation de charge),
+Partie 3 (DevOps), Partie 4 (Plan de tests), Partie 5 (Rétro-documentation),
+Partie 6 (Journal de bord).
+
+## Illustrations — Schémas d'architecture (Sections 10, 12, 13)
+
+![IMG:evidence/schema_infrastructure.png|Schéma d'architecture d'infrastructure Docker Compose (Section 12)]
+
+![IMG:evidence/schema_couches_logiques.png|Schéma d'architecture logique en 5 couches (Section 10)]