gesthub/docs/03_cahier_des_charges.md

# 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)]