docs: add functional and technical specifications for group creation app

This commit is contained in:
Mathis H (Avnyr) 2025-05-14 11:20:22 +02:00
parent 9487a8a801
commit 39ef07c4b4

610
cdc.md Normal file
View File

@ -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é