docs: update API integration and data model details

Updated documentation to reflect changes in the API GitHub integration, revised data model for tags, and introduced GDPR timestamp field. Enhanced diagrams and data schema descriptions for clarity.
2025-05-14 12:11:10 +02:00 · 2025-05-14 12:11:10 +02:00 · 8dc2069963
commit 8dc2069963
parent 51540836ee
1 changed files with 93 additions and 37 deletions
--- a/cdc.md
+++ b/cdc.md
@ -130,22 +130,27 @@ flowchart TB

    subgraph Storage["Stockage"]
        DB[(PostgreSQL)]
-        S3[("Stockage S3\n(Fichiers)")]
+    end
+
+    subgraph External["Services Externes"]
+        GH["API GitHub"]
    end

    FE <-->|"1. Requêtes HTTP/API REST"| BE
    FE <-->|"2. Communication temps réel"| WS
    BE <-->|"3. Requêtes SQL via DrizzleORM"| DB
-    BE <-->|"4. Stockage/Récupération de fichiers"| S3
+    BE <-->|"4. Récupération des avatars"| GH
    BE <-->|"5. Événements temps réel"| WS

    classDef client fill:#d8a0d8,stroke:#333,stroke-width:2px
    classDef server fill:#a0a0d8,stroke:#333,stroke-width:2px
    classDef storage fill:#a0d8a0,stroke:#333,stroke-width:2px
+    classDef external fill:#d8d8a0,stroke:#333,stroke-width:2px

    class Client client
    class Server server
    class Storage storage
+    class External external
 ```

 Ce diagramme montre les principaux flux d'interactions:
@ -165,10 +170,10 @@ Ce diagramme montre les principaux flux d'interactions:
   - Transactions pour garantir l'intégrité des données
   - Utilisation d'index pour des performances optimales

-4. **Backend ↔ Stockage S3**: Gestion des fichiers
-   - Stockage des avatars utilisateurs
-   - Sauvegarde des exports de données
-   - Gestion des pièces jointes
+4. **Backend ↔ API GitHub**: Récupération des données utilisateur
+   - Récupération des avatars utilisateurs
+   - Authentification des utilisateurs
+   - Récupération des informations de profil

 5. **Backend ↔ WebSocket**: Gestion des événements
   - Diffusion des mises à jour aux clients connectés
@ -187,10 +192,10 @@ Cette architecture permet une séparation claire des responsabilités tout en of
 #### 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`)
+   - avatar: String (URL depuis l'API Github, type `text`)
   - githubId: String (pour l'authentification OAuth, type `varchar(50)` avec index)
+   - gdprTimestamp: DateTime (timestamp d'acceptation RGPD, type `timestamptz`)
   - createdAt: DateTime (type `timestamptz` avec index)
   - updatedAt: DateTime (type `timestamptz`)
   - metadata: JSON (données flexibles, type `jsonb`)
@ -229,12 +234,13 @@ Cette architecture permet une séparation claire des responsabilités tout en of
   - createdAt: DateTime (type `timestamptz`)
   - updatedAt: DateTime (type `timestamptz`)

-5. **PersonTag**
+5. **Tag**
   - 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)
+   - type: Enum (PROJECT, PERSON, type `enum` natif PostgreSQL)
   - persons: Relation vers Person (table de jointure avec index)
+   - projects: Relation vers Project (table de jointure avec index)
   - createdAt: DateTime (type `timestamptz`)
   - updatedAt: DateTime (type `timestamptz`)

@ -243,11 +249,13 @@ Cette architecture permet une séparation claire des responsabilités tout en of
 - Un **Project** appartient à un seul **User**
 - Un **Project** contient plusieurs **Persons**
 - Un **Project** peut avoir plusieurs **Groups**
+- Un **Project** peut être associé à plusieurs **Tags** de type PROJECT
 - Une **Person** appartient à un seul **Project**
- Une **Person** peut être associée à plusieurs **PersonTags**
+- Une **Person** peut être associée à plusieurs **Tags** de type PERSON
 - Une **Person** peut être membre d'un seul **Group** à la fois
 - Un **Group** appartient à un seul **Project**
 - Un **Group** peut contenir plusieurs **Persons**
+- Les **Tags** sont globaux et gérés par les administrateurs

 #### 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.
@ -259,10 +267,10 @@ Le diagramme ci-dessous représente le modèle conceptuel de données de l'appli
 erDiagram
    USER {
        uuid id PK
-        string email
        string name
        string avatar
        string githubId
+        datetime gdprTimestamp
        datetime createdAt
        datetime updatedAt
        json metadata
@ -303,11 +311,11 @@ erDiagram
        datetime updatedAt
    }

-    PERSON_TAG {
+    TAG {
        uuid id PK
        string name
        string color
-        uuid projectId FK
+        enum type
        datetime createdAt
        datetime updatedAt
    }
@ -315,8 +323,8 @@ erDiagram
    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 à"
+    PROJECT }o--o{ TAG : "est associé à"
+    PERSON }o--o{ TAG : "est associée à"
    PERSON }o--|| GROUP : "est membre de"
 ```

@ -327,10 +335,10 @@ Le diagramme ci-dessous représente le modèle logique de données, montrant les
 erDiagram
    users {
        uuid id PK
-        varchar(255) email
        varchar(100) name
        text avatar
        varchar(50) githubId
+        timestamptz gdprTimestamp
        timestamptz createdAt
        timestamptz updatedAt
        jsonb metadata
@ -371,11 +379,11 @@ erDiagram
        timestamptz updatedAt
    }

-    person_tags {
+    tags {
        uuid id PK
        varchar(50) name
        varchar(7) color
-        uuid projectId FK
+        enum type
        timestamptz createdAt
        timestamptz updatedAt
    }
@ -394,14 +402,22 @@ erDiagram
        timestamptz createdAt
    }

+    project_to_tag {
+        uuid id PK
+        uuid projectId FK
+        uuid tagId FK
+        timestamptz createdAt
+    }
+
    users ||--o{ projects : "ownerId"
    projects ||--o{ persons : "projectId"
    projects ||--o{ groups : "projectId"
-    projects ||--o{ person_tags : "projectId"
+    projects ||--o{ project_to_tag : "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"
+    tags ||--o{ person_to_tag : "tagId"
+    tags ||--o{ project_to_tag : "tagId"
 ```

 ##### 2.3.3.3 Stratégie d'Indexation
@ -415,15 +431,16 @@ Pour optimiser les performances des requêtes, les stratégies d'indexation suiv
 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';
+import { pgTable, uuid, varchar, timestamp, 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 }),
+  githubId: varchar('githubId', { length: 50 }),
+  gdprTimestamp: timestamp('gdprTimestamp', { withTimezone: true }),
 }, (table) => {
  return {
-    emailIdx: index('email_idx').on(table.email),
+    githubIdIdx: index('githubId_idx').on(table.githubId),
    nameIdx: index('name_idx').on(table.name),
  };
 });
@ -448,28 +465,33 @@ flowchart TD
    User[Utilisateur] -->|Crée et gère| Project[Projet]
    Project -->|Contient| Person[Personnes]
    Project -->|Organise en| Group[Groupes]
+    Project -->|Associé à| Tag[Tags/Étiquettes]
    Person -->|Appartient à| Group
-    Person -->|Possède| Tag[Tags/Étiquettes]
+    Person -->|Associée à| Tag
+    Admin[Administrateur] -->|Gère| Tag

    classDef user fill:#d8a0d8,stroke:#333,stroke-width:2px
    classDef project fill:#a0a0d8,stroke:#333,stroke-width:2px
    classDef person fill:#a0d8a0,stroke:#333,stroke-width:2px
    classDef group fill:#d8a0a0,stroke:#333,stroke-width:2px
    classDef tag fill:#d8d8a0,stroke:#333,stroke-width:2px
+    classDef admin fill:#a0d8d8,stroke:#333,stroke-width:2px

    class User user
    class Project project
    class Person person
    class Group group
    class Tag tag
+    class Admin admin
 ```

 Ce diagramme illustre les concepts clés de l'application:
 - Un **Utilisateur** crée et gère des projets
- Chaque **Projet** contient des personnes et des groupes
- Les **Personnes** sont organisées en groupes et peuvent avoir des tags
+- Chaque **Projet** contient des personnes et des groupes et peut être associé à des tags
+- Les **Personnes** sont organisées en groupes et peuvent être associées à des tags
 - Les **Groupes** sont composés de personnes
- Les **Tags** permettent de catégoriser les personnes selon différents critères
+- Les **Tags** permettent de catégoriser les personnes et les projets selon différents critères
+- L'**Administrateur** gère les tags globaux utilisés dans toute l'application

 Cette représentation simplifiée permet aux parties prenantes non-techniques de comprendre facilement la structure générale de l'application sans avoir à se plonger dans les détails techniques du modèle de données.

@ -522,22 +544,27 @@ Cette représentation simplifiée permet aux parties prenantes non-techniques de
 - 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)
+  - Récupération des informations de base du profil (nom, avatar) depuis l'API GitHub
  - 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 administrateur pour la gestion globale:
+    - Gestion des tags globaux (création, modification, suppression)
+    - Attribution des types de tags (PROJECT, PERSON)
+    - Surveillance de l'utilisation des tags
+    - Gestion des utilisateurs et de leurs droits
  - 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
+  - Affichage de l'avatar récupéré depuis l'API GitHub
  - Gestion des préférences (notifications, thème, langue)
+  - Gestion du consentement RGPD (timestamp)
 - Tableau de bord personnel:
  - Vue d'ensemble des projets créés
  - Statistiques d'utilisation
@ -553,14 +580,43 @@ Cette représentation simplifiée permet aux parties prenantes non-techniques de
 - 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
+### 3.3 Système d'Administration
+
+#### 3.3.1 Interface d'Administration
+- Tableau de bord administrateur dédié:
+  - Vue d'ensemble de l'utilisation de l'application
+  - Statistiques sur les utilisateurs, projets, et tags
+  - Alertes et notifications système
+- Accès sécurisé réservé aux utilisateurs avec le rôle administrateur
+- Interface distincte de l'application principale
+
+#### 3.3.2 Gestion des Tags Globaux
+- Interface de création et gestion des tags:
+  - Création de nouveaux tags avec nom et couleur
+  - Définition du type de tag (PROJECT ou PERSON)
+  - Modification des tags existants
+  - Suppression des tags non utilisés
+- Visualisation de l'utilisation des tags:
+  - Nombre de projets et personnes associés à chaque tag
+  - Statistiques d'utilisation par utilisateur
+- Possibilité de fusionner des tags similaires
+- Exportation de la liste des tags au format CSV
+
+#### 3.3.3 Gestion des Utilisateurs
+- Liste complète des utilisateurs avec filtres et recherche
+- Modification des rôles utilisateur (administrateur, utilisateur standard, invité)
+- Surveillance de l'activité des utilisateurs
+- Possibilité de désactiver temporairement un compte utilisateur
+- Vérification du statut RGPD des utilisateurs
+
+### 3.4 Création et Gestion de Groupes
+#### 3.4.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
+#### 3.4.2 Attributs des Personnes
 Chaque personne dans le système sera caractérisée par les attributs suivants :
 - Prénom
 - Nom
@ -571,12 +627,12 @@ Chaque personne dans le système sera caractérisée par les attributs suivants
 - Niveau d'aisance à l'oral (timide, réservé, à l'aise)
 - Âge

-#### 3.3.3 Interface de Création Manuelle
+#### 3.4.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
+#### 3.4.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
@ -584,7 +640,7 @@ Chaque personne dans le système sera caractérisée par les attributs suivants
  - Groupes équilibrés pour la progression du niveau
  - Groupes équilibrés par niveau de compétence

-### 3.4 Communication en Temps Réel
+### 3.5 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