From 39ef07c4b4b7b37835fda4dbee0ad7e0bd0dfe35 Mon Sep 17 00:00:00 2001 From: Avnyr Date: Wed, 14 May 2025 11:20:22 +0200 Subject: [PATCH] docs: add functional and technical specifications for group creation app --- cdc.md | 610 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 610 insertions(+) create mode 100644 cdc.md diff --git a/cdc.md b/cdc.md new file mode 100644 index 0000000..5bcf125 --- /dev/null +++ b/cdc.md @@ -0,0 +1,610 @@ +# Cahier des Charges - Application de Création de Groupes + +## 1. Introduction + +### 1.1 Contexte du Projet +Ce document constitue le cahier des charges pour le développement d'une application web dédiée à la création et à la gestion de groupes. Cette application permettra aux utilisateurs de créer des groupes en prenant en compte divers paramètres et de conserver un historique des groupes précédemment créés. + +### 1.2 Objectifs du Projet +- Développer une application permettant la création de groupes selon différents critères +- Maintenir un historique des groupes créés pour éviter les duplications +- Offrir une interface intuitive et responsive +- Assurer la sécurité des données utilisateurs +- Respecter les normes RGPD + +## 2. Architecture Technique + +### 2.1 Stack Technologique +L'application sera développée en utilisant les technologies suivantes: + +#### Frontend: +- **NextJS**: Framework React pour le rendu côté serveur et la génération de sites statiques + - Utilisation des App Router et Server Components pour optimiser les performances + - Implémentation du SSR (Server-Side Rendering) pour améliorer le SEO et le temps de chargement initial + - Utilisation des API Routes pour les endpoints spécifiques au frontend + +- **ShadcnUI**: Bibliothèque de composants UI pour un design cohérent + - Composants accessibles et personnalisables + - Thèmes adaptables pour le mode clair/sombre + - Intégration avec Tailwind CSS pour la stylisation + +- **React Hook Form**: Gestion des formulaires + - Validation des données côté client + - Gestion efficace des erreurs de formulaire + - Intégration avec Zod pour la validation de schéma + +- **Motion**: Bibliothèque pour les animations et le dynamisme de l'interface + - Animations fluides et performantes + - Transitions entre les pages + - Effets visuels pour améliorer l'expérience utilisateur + +#### Backend: +- **NestJS**: Framework Node.js pour construire des applications serveur efficaces et scalables + - Architecture modulaire basée sur les décorateurs + - Injection de dépendances pour une meilleure testabilité + - Support intégré pour TypeScript + - Utilisation des Guards, Interceptors et Pipes pour la gestion des requêtes + +- **PostgreSQL**: Système de gestion de base de données relationnelle + - Modélisation des données avec relations complexes + - Utilisation de DrizzleORM comme ORM pour interagir avec la base de données + - Migrations SQL déclaratives et type-safe + - Approche code-first pour la définition du schéma + - Optimisation des formats de données PostgreSQL (JSONB pour les données flexibles, UUID pour les identifiants, ENUM pour les valeurs fixes) + - Stratégie d'indexation avancée pour améliorer les performances des requêtes + +- **SocketIO**: Bibliothèque pour la communication en temps réel + - Mise à jour instantanée des groupes + - Notifications en temps réel + - Collaboration simultanée entre utilisateurs + +- **@node-rs/argon2**: Bibliothèque pour le hachage sécurisé des mots de passe + - Implémentation en Rust pour des performances optimales + - Protection contre les attaques par force brute + - Configuration adaptée aux recommandations de sécurité actuelles + +- **jose**: Bibliothèque pour la gestion des JWT (JSON Web Tokens) + - Authentification stateless + - Signature et vérification des tokens + - Gestion des expirations et du rafraîchissement des tokens + +#### Authentification: +- **OAuth2.0 + OIDC**: Via compte GitHub pour l'authentification sécurisée + - Flux d'autorisation code avec PKCE + - Récupération des informations de profil via l'API GitHub + - Gestion des scopes pour limiter les accès + - Implémentation côté backend pour sécuriser le processus d'authentification + +### 2.2 Architecture Applicative +L'application suivra une architecture monorepo avec séparation claire entre le frontend et le backend. + +#### 2.2.1 Structure du Monorepo +``` +/ +├── apps/ +│ ├── web/ # Application frontend NextJS +│ │ ├── public/ # Fichiers statiques +│ │ ├── src/ +│ │ │ ├── app/ # App Router de NextJS +│ │ │ ├── components/ # Composants React réutilisables +│ │ │ ├── hooks/ # Custom hooks React +│ │ │ ├── lib/ # Utilitaires et configurations +│ │ │ └── styles/ # Styles globaux +│ │ └── ... +│ │ +│ └── api/ # Application backend NestJS +│ ├── src/ +│ │ ├── modules/ # Modules NestJS +│ │ ├── common/ # Utilitaires partagés +│ │ ├── config/ # Configuration de l'application +│ │ └── main.ts # Point d'entrée de l'application +│ └── ... +│ +├── packages/ # Packages partagés +│ ├── database/ # Configuration DrizzleORM et modèles +│ ├── eslint-config/ # Configuration ESLint partagée +│ ├── tsconfig/ # Configuration TypeScript partagée +│ └── ui/ # Bibliothèque de composants UI partagés +│ +└── ... +``` + +#### 2.2.2 Communication entre les Services +- API REST pour les opérations CRUD standard +- WebSockets via SocketIO pour les communications en temps réel +- Authentification via JWT pour sécuriser les échanges + +#### 2.2.3 Déploiement +- Conteneurisation avec Docker pour assurer la cohérence entre les environnements +- CI/CD via GitHub Actions pour l'intégration et le déploiement continus +- Infrastructure scalable pour gérer les pics de charge + +### 2.3 Modèle de Données + +#### 2.3.1 Entités Principales +1. **User** + - id: UUIDv7 (clé primaire, type `uuid` optimisé pour l'indexation) + - email: String (unique, type `varchar(255)` avec index) + - name: String (type `varchar(100)`) + - avatar: String (URL, type `text`) + - githubId: String (pour l'authentification OAuth, type `varchar(50)` avec index) + - createdAt: DateTime (type `timestamptz` avec index) + - updatedAt: DateTime (type `timestamptz`) + - metadata: JSON (données flexibles, type `jsonb`) + +2. **Project** + - id: UUIDv7 (clé primaire, type `uuid` optimisé pour l'indexation) + - name: String (type `varchar(100)` avec index) + - description: String (type `text`) + - ownerId: UUID (clé étrangère vers User, type `uuid` avec index) + - settings: JSON (configurations personnalisées, type `jsonb`) + - createdAt: DateTime (type `timestamptz` avec index) + - updatedAt: DateTime (type `timestamptz`) + +3. **Person** + - id: UUIDv7 (clé primaire, type `uuid` optimisé pour l'indexation) + - firstName: String (type `varchar(50)` avec index partiel) + - lastName: String (type `varchar(50)` avec index partiel) + - gender: Enum (MALE, FEMALE, NON_BINARY, type `enum` natif PostgreSQL) + - technicalLevel: Integer (type `smallint` pour économie d'espace) + - hasTechnicalTraining: Boolean (type `boolean`) + - frenchSpeakingLevel: Integer (type `smallint` pour économie d'espace) + - oralEaseLevel: Enum (SHY, RESERVED, COMFORTABLE, type `enum` natif PostgreSQL) + - age: Integer (type `smallint` pour économie d'espace) + - projectId: UUID (clé étrangère vers Project, type `uuid` avec index) + - attributes: JSON (attributs additionnels flexibles, type `jsonb`) + - tags: Relation vers PersonTag (table de jointure avec index) + - createdAt: DateTime (type `timestamptz`) + - updatedAt: DateTime (type `timestamptz`) + +4. **Group** + - id: UUIDv7 (clé primaire, type `uuid` optimisé pour l'indexation) + - name: String (type `varchar(100)` avec index) + - projectId: UUID (clé étrangère vers Project, type `uuid` avec index) + - metadata: JSON (données additionnelles, type `jsonb`) + - members: Relation vers Person (table de jointure avec index) + - createdAt: DateTime (type `timestamptz`) + - updatedAt: DateTime (type `timestamptz`) + +5. **PersonTag** + - id: UUIDv7 (clé primaire, type `uuid` optimisé pour l'indexation) + - name: String (type `varchar(50)` avec index) + - color: String (code couleur, type `varchar(7)`) + - projectId: UUID (clé étrangère vers Project, type `uuid` avec index) + - persons: Relation vers Person (table de jointure avec index) + - createdAt: DateTime (type `timestamptz`) + - updatedAt: DateTime (type `timestamptz`) + +#### 2.3.2 Relations +- Un **User** peut avoir plusieurs **Projects** +- Un **Project** appartient à un seul **User** +- Un **Project** contient plusieurs **Persons** +- Un **Project** peut avoir plusieurs **Groups** +- Une **Person** appartient à un seul **Project** +- Une **Person** peut être associée à plusieurs **PersonTags** +- Une **Person** peut être membre d'un seul **Group** à la fois +- Un **Group** appartient à un seul **Project** +- Un **Group** peut contenir plusieurs **Persons** + +#### 2.3.3 Schéma de Base de Données +Le schéma sera implémenté via DrizzleORM, permettant une définition type-safe des tables et relations avec une approche code-first. Les migrations SQL seront générées automatiquement à partir des changements de schéma, offrant un contrôle précis sur l'évolution de la base de données. + +##### 2.3.3.1 Modèle Conceptuel de Données (MCD) +Le diagramme ci-dessous représente le modèle conceptuel de données de l'application, montrant les entités et leurs relations: + +```mermaid +erDiagram + USER { + uuid id PK + string email + string name + string avatar + string githubId + datetime createdAt + datetime updatedAt + json metadata + } + + PROJECT { + uuid id PK + string name + string description + uuid ownerId FK + json settings + datetime createdAt + datetime updatedAt + } + + PERSON { + uuid id PK + string firstName + string lastName + enum gender + int technicalLevel + boolean hasTechnicalTraining + int frenchSpeakingLevel + enum oralEaseLevel + int age + uuid projectId FK + json attributes + datetime createdAt + datetime updatedAt + } + + GROUP { + uuid id PK + string name + uuid projectId FK + json metadata + datetime createdAt + datetime updatedAt + } + + PERSON_TAG { + uuid id PK + string name + string color + uuid projectId FK + datetime createdAt + datetime updatedAt + } + + USER ||--o{ PROJECT : "possède" + PROJECT ||--o{ PERSON : "contient" + PROJECT ||--o{ GROUP : "contient" + PROJECT ||--o{ PERSON_TAG : "contient" + PERSON }o--o{ PERSON_TAG : "est associée à" + PERSON }o--|| GROUP : "est membre de" +``` + +##### 2.3.3.2 Modèle Logique de Données (MLD) +Le diagramme ci-dessous représente le modèle logique de données, montrant les tables, leurs champs et les relations entre elles: + +```mermaid +erDiagram + users { + uuid id PK + varchar(255) email + varchar(100) name + text avatar + varchar(50) githubId + timestamptz createdAt + timestamptz updatedAt + jsonb metadata + } + + projects { + uuid id PK + varchar(100) name + text description + uuid ownerId FK + jsonb settings + timestamptz createdAt + timestamptz updatedAt + } + + persons { + uuid id PK + varchar(50) firstName + varchar(50) lastName + enum gender + smallint technicalLevel + boolean hasTechnicalTraining + smallint frenchSpeakingLevel + enum oralEaseLevel + smallint age + uuid projectId FK + jsonb attributes + timestamptz createdAt + timestamptz updatedAt + } + + groups { + uuid id PK + varchar(100) name + uuid projectId FK + jsonb metadata + timestamptz createdAt + timestamptz updatedAt + } + + person_tags { + uuid id PK + varchar(50) name + varchar(7) color + uuid projectId FK + timestamptz createdAt + timestamptz updatedAt + } + + person_to_group { + uuid id PK + uuid personId FK + uuid groupId FK + timestamptz createdAt + } + + person_to_tag { + uuid id PK + uuid personId FK + uuid tagId FK + timestamptz createdAt + } + + users ||--o{ projects : "ownerId" + projects ||--o{ persons : "projectId" + projects ||--o{ groups : "projectId" + projects ||--o{ person_tags : "projectId" + persons ||--o{ person_to_group : "personId" + groups ||--o{ person_to_group : "groupId" + persons ||--o{ person_to_tag : "personId" + person_tags ||--o{ person_to_tag : "tagId" +``` + +##### 2.3.3.3 Stratégie d'Indexation +Pour optimiser les performances des requêtes, les stratégies d'indexation suivantes seront mises en place: +- Index primaires sur toutes les clés primaires (UUIDv7) +- Index secondaires sur les clés étrangères pour accélérer les jointures +- Index composites sur les champs fréquemment utilisés ensemble dans les requêtes +- Index partiels pour les requêtes filtrées fréquentes +- Index de texte pour les recherches sur les champs textuels (noms, descriptions) + +DrizzleORM facilite la définition de ces index directement dans le schéma avec une syntaxe déclarative: +```typescript +// Exemple de définition d'index avec DrizzleORM +import { pgTable, uuid, varchar, index } from 'drizzle-orm/pg-core'; + +export const users = pgTable('users', { + id: uuid('id').primaryKey().defaultRandom(), + email: varchar('email', { length: 255 }).notNull().unique(), + name: varchar('name', { length: 255 }), +}, (table) => { + return { + emailIdx: index('email_idx').on(table.email), + nameIdx: index('name_idx').on(table.name), + }; +}); +``` + +##### 2.3.3.4 Optimisation des Formats de Données +Les types de données PostgreSQL seront optimisés pour chaque cas d'usage: +- Utilisation de `UUID` pour les identifiants (UUIDv7 pour l'ordre chronologique) +- Type `JSONB` pour les données flexibles et semi-structurées +- Types `ENUM` PostgreSQL natifs pour les valeurs fixes (genres, niveaux d'aisance) +- Type `TEXT` avec contraintes pour les chaînes de caractères variables +- Types `TIMESTAMP WITH TIME ZONE` pour les dates avec gestion des fuseaux horaires +- Utilisation de `NUMERIC` pour les valeurs nécessitant une précision exacte + +Ces optimisations permettront d'améliorer les performances des requêtes, de réduire l'empreinte mémoire et d'assurer l'intégrité des données. + +## 3. Spécifications Fonctionnelles + +### 3.1 Interface Utilisateur + +#### 3.1.1 Principes Généraux +- Approche "mobile first" pour l'ensemble du site +- Interface de type dashboard pour le frontend +- Design responsive s'adaptant à tous les appareils (mobile, tablette, desktop) +- Accessibilité conforme aux normes WCAG 2.1 niveau AA +- Thème clair/sombre avec détection automatique des préférences système + +#### 3.1.2 Structure Globale +- **Header**: + - Logo et nom de l'application + - Navigation principale + - Fonctionnalités de gestion de compte et de connexion + - Recherche de projets enregistrés + - Indicateur de notifications + +- **Footer**: + - Liens vers les pages légales obligatoires (CGU, Politique de confidentialité, Mentions légales) + - Liens vers la documentation + - Informations de contact + - Sélecteur de langue + +- **Page d'accueil**: + - Présentation des fonctionnalités aux utilisateurs anonymes + - Bac à sable interactif pour tester l'application sans inscription + - Témoignages et cas d'utilisation + - Appel à l'action pour la création de compte + +- **Dashboard**: + - Vue d'ensemble des projets de l'utilisateur + - Statistiques et métriques sur l'utilisation + - Accès rapide aux fonctionnalités principales + - Notifications et alertes + +#### 3.1.3 Composants UI Spécifiques +- Utilisation de ShadcnUI pour les composants de base (boutons, champs de formulaire, modales, etc.) +- Animations et transitions avec Motion pour améliorer l'expérience utilisateur +- Formulaires optimisés avec React Hook Form pour une validation instantanée +- Visualisations interactives pour les groupes créés + +### 3.2 Gestion des Utilisateurs + +#### 3.2.1 Inscription et Authentification +- Création de compte utilisateur obligatoire pour utiliser pleinement les fonctionnalités +- Authentification via OAuth2.0 avec GitHub: + - Flux d'authentification sécurisé avec redirection vers GitHub + - Récupération des informations de base du profil (nom, email, avatar) + - Possibilité d'étendre à d'autres fournisseurs d'identité dans le futur +- Gestion des sessions utilisateur avec JWT (JSON Web Tokens): + - Token d'accès avec durée de validité limitée (15 minutes) + - Token de rafraîchissement pour prolonger la session (validité de 7 jours) + - Révocation des tokens en cas de déconnexion ou de suspicion de compromission +- Gestion des autorisations basée sur les rôles (RBAC): + - Rôle administrateur pour la gestion globale + - Rôle utilisateur standard pour la création et gestion de projets personnels + - Rôle invité pour l'accès en lecture seule à des projets partagés + +#### 3.2.2 Profil Utilisateur +- Gestion des informations personnelles: + - Modification du nom d'affichage + - Mise à jour de l'avatar + - Gestion des préférences (notifications, thème, langue) +- Tableau de bord personnel: + - Vue d'ensemble des projets créés + - Statistiques d'utilisation + - Activité récente +- Gestion des notifications: + - Alertes système + - Rappels pour les projets en cours + - Notifications de partage + +#### 3.2.3 Gestion des Données Utilisateur +- Accès à l'historique des projets de groupe enregistrés +- Export des données personnelles au format JSON ou CSV +- Suppression de compte avec option de conservation ou suppression des projets +- Conformité RGPD avec droit à l'oubli et portabilité des données + +### 3.3 Création et Gestion de Groupes +#### 3.3.1 Création de Projet de Groupe +- Possibilité de créer une liste de personnes qui seront placées dans les groupes +- Attribution de "tags" aux personnes +- Définition d'échelles de niveau personnalisées +- Nom de projet unique à l'échelle de l'utilisateur + +#### 3.3.2 Attributs des Personnes +Chaque personne dans le système sera caractérisée par les attributs suivants : +- Prénom +- Nom +- Genre (Masculin, féminin, non binaire) +- Niveau d'aisance technique +- Expérience préalable en formation technique +- Capacité d'expression en français +- Niveau d'aisance à l'oral (timide, réservé, à l'aise) +- Âge + +#### 3.3.3 Interface de Création Manuelle +- Affichage de la liste des personnes sur le côté (format desktop minimum) +- Possibilité de réaliser manuellement les groupes +- Option de renommer chaque groupe manuellement + +#### 3.3.4 Assistant à la Création de Groupe +- Fonctionnalité de création aléatoire de groupes +- L'utilisateur définit le nombre de groupes souhaités +- Attribution obligatoire d'un nom à chaque groupe +- Sélection de presets pour la génération de groupes équilibrés: + - Groupes équilibrés pour la progression du niveau + - Groupes équilibrés par niveau de compétence + +### 3.4 Communication en Temps Réel +- Utilisation de SocketIO pour les mises à jour en temps réel +- Notification des modifications de groupes aux utilisateurs concernés +- Collaboration possible entre utilisateurs sur un même projet de groupe + +## 4. Exigences Techniques + +### 4.1 Développement +- Respect des principes SOLID +- Application des conventions de nommage standard +- Tests unitaires et tests e2e de l'API +- Documentation technique complète + +### 4.2 Sécurité et Conformité + +#### 4.2.1 Protection des Données +- Chiffrement des données sensibles en base de données +- Hachage sécurisé des mots de passe avec @node-rs/argon2: + - Utilisation de sel unique pour chaque utilisateur + - Paramètres de hachage conformes aux recommandations OWASP + - Implémentation en Rust pour des performances optimales et une résistance aux attaques par force brute +- Gestion des tokens JWT avec la bibliothèque jose: + - Signatures avec algorithme RS256 + - Rotation des clés de signature + - Validation complète des tokens (signature, expiration, émetteur) +- Mise en place de mécanismes de défense contre les attaques courantes: + - Protection CSRF (Cross-Site Request Forgery) + - Protection XSS (Cross-Site Scripting) + - Protection contre les injections SQL + - Rate limiting pour prévenir les attaques par force brute + +#### 4.2.2 Conformité RGPD +- Conformité aux exigences RGPD et aux lois françaises: + - Minimisation des données collectées + - Finalité claire de la collecte de données + - Durée de conservation limitée et justifiée +- Mise en œuvre des droits des utilisateurs: + - Droit d'accès aux données personnelles + - Droit de rectification + - Droit à l'effacement (droit à l'oubli) + - Droit à la portabilité des données + - Droit d'opposition au traitement +- Renouvellement du consentement utilisateur tous les 13 mois pour les conditions générales d'utilisation et les cookies +- Registre des activités de traitement +- Procédure de notification en cas de violation de données + +#### 4.2.3 Audit et Traçabilité +- Journalisation des actions sensibles: + - Connexions et déconnexions + - Modifications de données importantes + - Accès aux données personnelles +- Conservation des logs pendant une durée conforme aux exigences légales +- Système d'alerte en cas d'activité suspecte +- Audits de sécurité réguliers + +### 4.3 Performance et Monitoring + +#### 4.3.1 Objectifs de Performance +- Temps de chargement initial < 2 secondes (95ème percentile) +- Temps de réponse API < 300ms (95ème percentile) +- Temps d'exécution des requêtes SQL complexes < 100ms (95ème percentile) +- Disponibilité > 99.9% +- Support de 1000 utilisateurs simultanés minimum +- Utilisation efficiente des index pour les requêtes fréquentes + +#### 4.3.2 Optimisation de la Base de Données +- Analyse régulière des plans d'exécution des requêtes avec `EXPLAIN ANALYZE` +- Mise en place d'un processus de maintenance automatisé: + - VACUUM régulier pour récupérer l'espace disque + - ANALYZE pour mettre à jour les statistiques du planificateur + - REINDEX pour maintenir l'efficacité des index +- Partitionnement des tables volumineuses pour améliorer les performances +- Utilisation de la mise en cache des requêtes fréquentes +- Optimisation des requêtes N+1 via l'utilisation appropriée des jointures et des relations + +#### 4.3.3 Monitoring et Observabilité +- Mise en place d'outils de monitoring: + - Métriques d'application (temps de réponse, taux d'erreur) + - Métriques système (CPU, mémoire, disque) + - Métriques utilisateur (nombre de sessions, actions effectuées) + - Métriques de base de données: + - Temps d'exécution des requêtes + - Utilisation des index + - Taux de cache hit/miss + - Nombre de connexions actives + - Taille des tables et des index +- Alerting automatique en cas de dégradation des performances +- Tableau de bord de supervision pour l'équipe technique +- Analyse des logs centralisée +- Traçage des requêtes lentes avec pg_stat_statements + +## 5. Planification et Livrables + +### 5.1 Phases du Projet +1. **Phase de conception** (2 semaines) + - Finalisation des maquettes UI/UX + - Conception de l'architecture technique + - Modélisation de la base de données + +2. **Phase de développement** (8 semaines) + - Développement du backend (NestJS, PostgreSQL) + - Développement du frontend (NextJS, ShadcnUI) + - Intégration de l'authentification OAuth2.0 + +3. **Phase de test** (2 semaines) + - Tests unitaires et e2e + - Tests de performance + - Tests de sécurité + +4. **Phase de déploiement** (1 semaine) + - Mise en production + - Formation des utilisateurs + - Documentation finale + +### 5.2 Livrables +- Code source complet (frontend et backend) +- Documentation technique +- Documentation utilisateur +- Rapport de tests +- Environnement de production déployé