9.6 KiB
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 | 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)]