📄 Cahier des Charges - Application Corpo Padel

1. Introduction

1.1 Contexte du projet

Ce projet pédagogique s'inscrit dans le cadre d'un cours de test et sécurité pour étudiants ingénieurs. L'objectif est de développer une application web complète pour gérer les tournois de padel corporatifs d'une entreprise.

L'application doit permettre aux administrateurs de gérer l'ensemble des tournois (planification, équipes, résultats) et aux joueurs de suivre leur progression et leurs prochains matchs.

1.2 Objectifs pédagogiques

Ce projet vous permettra de mettre en pratique les compétences suivantes :

• Développement Full-Stack : Créer une application complète avec frontend VueJS et backend FastAPI
• Tests automatisés : Implémenter des tests unitaires (Python) et End-to-End (Cypress)
• Sécurité applicative : Mettre en œuvre les bonnes pratiques de sécurité (validation, XSS, authentification)
• Gestion de base de données : Concevoir et manipuler un schéma de données cohérent
• Documentation : Rédiger un rapport technique complet

1.3 Glossaire

2. Spécifications Fonctionnelles

2.1 Gestion des rôles et authentification

2.1.1 Les trois rôles

2.1.2 Processus d'authentification

Flux d'authentification :

1. L'utilisateur saisit son email et mot de passe
2. Le backend vérifie les credentials
3. Si valides, un JWT est généré contenant : user_id, email, role, exp
4. Le token est retourné au client et stocké
5. Chaque requête ultérieure inclut le token dans le header Authorization

2.1.3 Mécanisme anti-brute force

Règles :

• Maximum 5 tentatives de connexion échouées
• Blocage du compte pendant 30 minutes après 5 échecs
• Le compteur se réinitialise après une connexion réussie
• L'utilisateur doit recevoir un message clair indiquant le nombre de tentatives restantes
• Après blocage, afficher le temps restant avant déblocage

Implémentation technique :

Table: login_attempts
- email (TEXT)
- attempts_count (INTEGER)
- last_attempt (DATETIME)
- locked_until (DATETIME nullable)

2.2 Page d'accueil

2.2.1 Objectif

Page d'atterrissage simple et accueillante présentant l'application.

2.2.2 Contenu

• Une image ou bannière évoquant le padel corporatif
• Un message de bienvenue expliquant brièvement l'application
• Un bouton "Se connecter" bien visible

2.2.3 Comportement

2.3 Planning

2.3.1 Objectif

Visualiser tous les événements de la saison sous forme de calendrier.

2.3.2 Vue calendrier

Affichage :

• Vue mensuelle par défaut
• Possibilité de naviguer entre les mois
• Chaque jour contenant un événement est marqué visuellement
• Clic sur un jour affiche les événements de cette date

2.3.3 Structure d'un événement

2.3.4 Structure d'un match

2.3.5 Droits par rôle

Joueur

• Voir le calendrier complet
• Cliquer sur un événement pour voir les détails (date, heure, matchs)
• Voir uniquement les événements où ils sont impliqués (filtre automatique)
• Option pour voir tous les événements (décocher le filtre)

Administrateur

• Toutes les actions du joueur
• Ajouter un événement (formulaire avec date, heure, sélection des matchs)
• Modifier un événement existant
• Supprimer un événement

2.3.6 Formulaire d'ajout d'événement (Admin)

Champs :

• Date (obligatoire, datepicker, min: aujourd'hui)
• Heure (obligatoire, format HH:MM)
• Nombre de matchs (1, 2 ou 3)
• Pour chaque match :
  • Numéro de piste (select 1-10)
  • Équipe 1 (select parmi les équipes)
  • Équipe 2 (select parmi les équipes)

Validations :

• La date doit être >= date du jour
• L'heure doit être au format HH:MM (00:00 à 23:59)
• Deux matchs ne peuvent pas utiliser la même piste pour le même événement
• Une équipe ne peut jouer qu'un seul match par événement

2.4 Matchs

2.4.1 Objectif

Afficher la liste des matchs à venir dans les 30 prochains jours sous forme de liste.

2.4.2 Affichage par défaut

2.4.3 Filtre

Pour les joueurs

• Par défaut : Affiche uniquement les matchs de leur(s) équipe(s)
• Option : Case à cocher "Voir tous les matchs" pour désactiver le filtre

Pour les administrateurs

• Par défaut : Affiche tous les matchs
• Options de filtre :
  • Par entreprise
  • Par poule
  • Par statut

2.4.4 Actions administrateur

Ajouter un match

Formulaire avec les champs suivants :

• Date (YYYY-MM-DD, >= aujourd'hui)
• Heure (HH:MM)
• Piste (1-10)
• Équipe 1 (select)
• Équipe 2 (select)

Modifier un match

• Modifier la date/heure (si statut = A_VENIR)
• Changer la piste
• Modifier le statut (A_VENIR → ANNULE)
• Saisir les scores (si match terminé)

Supprimer un match

• Possible uniquement si statut = A_VENIR
• Confirmation obligatoire

2.5 Résultats

2.5.1 Objectif

Consulter les résultats des matchs terminés et le classement général.

2.5.2 Vue des résultats personnels (Joueur)

Affichage :

• Liste chronologique (du plus récent au plus ancien)
• Uniquement les matchs avec statut = TERMINE
• Filtre : "Depuis le début de la saison" par défaut

Informations par match :

2.5.3 Classement général des entreprises

Règles de classement :

1. Total de points
2. En cas d'égalité : nombre de victoires
3. En cas d'égalité : différence de sets gagnés/perdus
4. En cas d'égalité : ordre alphabétique

2.5.4 Format des scores

Règles de validation :

• Chaque set doit être au format "X-Y" où X et Y sont des entiers
• Le vainqueur d'un set doit avoir au moins 6 jeux
• Si un set se termine 7-X, X doit être <= 5
• Si un set se termine 7-6, c'est un tie-break
• Un match se joue au meilleur de 3 sets (2 ou 3 sets maximum)

2.6 Administration

2.6.1 Gestion des joueurs

Ajouter un joueur

Formulaire :

Modifier un joueur

• Tous les champs sauf le numéro de licence et l'email
• Validation identique à la création

Supprimer un joueur

• Possible uniquement si le joueur n'est dans aucune équipe active
• Confirmation obligatoire avec message : "Attention, cette action est irréversible"

2.6.2 Gestion des équipes

Structure d'une équipe

Règles de validation

• Les deux joueurs doivent appartenir à la même entreprise
• Un joueur ne peut être que dans une seule équipe par saison
• Une équipe ne peut être dans qu'une seule poule

Actions

• Créer : Sélectionner entreprise + 2 joueurs
• Modifier : Changer les joueurs (si aucun match joué)
• Supprimer : Possible uniquement si aucun match n'a été joué

2.6.3 Gestion des poules

Structure d'une poule

Actions

• Créer : Nommer la poule + sélectionner 6 équipes
• Modifier : Changer les équipes (toutes les équipes doivent être sans matchs joués)
• Supprimer : Possible uniquement si aucun match n'a été joué dans cette poule

2.6.4 Gestion des comptes

Créer un compte pour un joueur

Prérequis : Le joueur doit déjà exister dans la base

Processus :

1. Sélectionner un joueur existant sans compte
2. Le système génère automatiquement :
   • Email : celui du joueur
   • Mot de passe temporaire : généré aléatoirement
   • Rôle : JOUEUR par défaut
3. Afficher le mot de passe temporaire (une seule fois)
4. L'utilisateur devra changer son mot de passe à la première connexion

Réinitialiser un mot de passe

• Génération d'un nouveau mot de passe temporaire
• Affichage une seule fois à l'admin
• Changement obligatoire à la prochaine connexion

2.7 Profil

2.7.1 Objectif

Permettre à chaque utilisateur de consulter et modifier ses informations personnelles.

2.7.2 Informations affichées

2.7.3 Règles de validation

• Nom/Prénom : Lettres, espaces, tirets et apostrophes uniquement
• Date de naissance :
  • L'utilisateur doit avoir au moins 16 ans
  • Date ne peut pas être dans le futur
• Email :
  • Format valide (regex standard)
  • Unique dans la base de données
• Photo :
  • Formats acceptés : .jpg, .jpeg, .png
  • Taille maximale : 2MB
  • Dimensions recommandées : 400x400px

2.7.4 Changement de mot de passe

Formulaire :

• Mot de passe actuel (obligatoire)
• Nouveau mot de passe (obligatoire)
• Confirmation du nouveau mot de passe (obligatoire)

Règles de validation :

• Le mot de passe actuel doit être correct
• Le nouveau mot de passe doit respecter la politique de sécurité (voir section 4.4)
• Les deux nouveaux mots de passe doivent correspondre
• Le nouveau mot de passe doit être différent de l'ancien

3. Spécifications Techniques

3.1 Architecture système

3.1.1 Architecture globale

┌─────────────────────────────────────────────┐
│           CLIENT (Browser)                   │
│                                              │
│  ┌────────────────────────────────────┐    │
│  │         VueJS 3.x                   │    │
│  │  - Vue Router                       │    │
│  │  - Axios (HTTP client)              │    │
│  │  - TailwindCSS                      │    │
│  └────────────────────────────────────┘    │
└──────────────────┬──────────────────────────┘
                   │ HTTP/HTTPS
                   │ REST API
┌──────────────────▼──────────────────────────┐
│           SERVER                             │
│                                              │
│  ┌────────────────────────────────────┐    │
│  │       FastAPI (Python 3.11+)        │    │
│  │  - JWT Authentication               │    │
│  │  - Pydantic Validation              │    │
│  │  - SQLAlchemy ORM                   │    │
│  │  - Password Hashing (bcrypt)        │    │
│  └────────────────┬───────────────────┘    │
│                   │                          │
│  ┌────────────────▼───────────────────┐    │
│  │       SQLite Database               │    │
│  │  - File: padel_corpo.db             │    │
│  └────────────────────────────────────┘    │
└─────────────────────────────────────────────┘

3.1.2 Stack technologique imposée

3.2 Modèle de données

3.2.1 Diagramme ERD

┌──────────────────┐         ┌──────────────────┐
│   users          │         │   players        │
├──────────────────┤         ├──────────────────┤
│ id (PK)          │────────▶│ id (PK)          │
│ email (UNIQUE)   │         │ first_name       │
│ password_hash    │         │ last_name        │
│ role             │         │ company          │
│ is_active        │         │ license_number   │
│ created_at       │         │ birth_date       │
└──────────────────┘         │ photo_url        │
                              │ user_id (FK)     │
                              └─────┬────────────┘
                                    │
                         ┌──────────┴──────────┐
                         │                      │
                         ▼                      ▼
              ┌──────────────────┐   ┌──────────────────┐
              │   teams          │   │   matches        │
              ├──────────────────┤   ├──────────────────┤
              │ id (PK)          │   │ id (PK)          │
              │ company          │───│ team1_id (FK)    │
              │ player1_id (FK)  │   │ team2_id (FK)    │
              │ player2_id (FK)  │   │ event_id (FK)    │
              │ pool_id (FK)     │   │ court_number     │
              └──────┬───────────┘   │ status           │
                     │                │ score_team1      │
                     │                │ score_team2      │
                     │                └──────────────────┘
                     ▼
              ┌──────────────────┐         ┌──────────────────┐
              │   pools          │         │   events         │
              ├──────────────────┤         ├──────────────────┤
              │ id (PK)          │         │ id (PK)          │
              │ name (UNIQUE)    │         │ event_date       │
              │ created_at       │         │ event_time       │
              └──────────────────┘         │ created_at       │
                                            └──────────────────┘

┌──────────────────────┐
│   login_attempts     │
├──────────────────────┤
│ id (PK)              │
│ email                │
│ attempts_count       │
│ last_attempt         │
│ locked_until         │
└──────────────────────┘

3.2.2 Schéma SQL détaillé

-- Table users
CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT NOT NULL UNIQUE,
    password_hash TEXT NOT NULL,
    role TEXT NOT NULL CHECK(role IN ('JOUEUR', 'ADMINISTRATEUR')),
    is_active BOOLEAN DEFAULT TRUE,
    must_change_password BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Table players
CREATE TABLE players (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    first_name TEXT NOT NULL,
    last_name TEXT NOT NULL,
    company TEXT NOT NULL,
    license_number TEXT NOT NULL UNIQUE,
    birth_date DATE,
    photo_url TEXT,
    user_id INTEGER UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE SET NULL,
    CONSTRAINT chk_license_format CHECK(license_number GLOB 'L[0-9][0-9][0-9][0-9][0-9][0-9]')
);

-- Table pools
CREATE TABLE pools (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Table teams
CREATE TABLE teams (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    company TEXT NOT NULL,
    player1_id INTEGER NOT NULL,
    player2_id INTEGER NOT NULL,
    pool_id INTEGER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (player1_id) REFERENCES players(id) ON DELETE CASCADE,
    FOREIGN KEY (player2_id) REFERENCES players(id) ON DELETE CASCADE,
    FOREIGN KEY (pool_id) REFERENCES pools(id) ON DELETE SET NULL,
    CONSTRAINT chk_different_players CHECK(player1_id != player2_id)
);

-- Table events
CREATE TABLE events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    event_date DATE NOT NULL,
    event_time TIME NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Table matches
CREATE TABLE matches (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    event_id INTEGER NOT NULL,
    team1_id INTEGER NOT NULL,
    team2_id INTEGER NOT NULL,
    court_number INTEGER NOT NULL CHECK(court_number BETWEEN 1 AND 10),
    status TEXT NOT NULL DEFAULT 'A_VENIR' CHECK(status IN ('A_VENIR', 'TERMINE', 'ANNULE')),
    score_team1 TEXT,
    score_team2 TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (event_id) REFERENCES events(id) ON DELETE CASCADE,
    FOREIGN KEY (team1_id) REFERENCES teams(id) ON DELETE CASCADE,
    FOREIGN KEY (team2_id) REFERENCES teams(id) ON DELETE CASCADE,
    CONSTRAINT chk_different_teams CHECK(team1_id != team2_id)
);

-- Table login_attempts
CREATE TABLE login_attempts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT NOT NULL,
    attempts_count INTEGER DEFAULT 0,
    last_attempt TIMESTAMP,
    locked_until TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Indexes pour performances
CREATE INDEX idx_players_user_id ON players(user_id);
CREATE INDEX idx_teams_players ON teams(player1_id, player2_id);
CREATE INDEX idx_teams_pool ON teams(pool_id);
CREATE INDEX idx_matches_event ON matches(event_id);
CREATE INDEX idx_matches_teams ON matches(team1_id, team2_id);
CREATE INDEX idx_matches_status ON matches(status);
CREATE INDEX idx_events_date ON events(event_date);
CREATE INDEX idx_login_attempts_email ON login_attempts(email);

3.3 API REST

3.3.1 Convention de nommage

• Base URL : http://localhost:8000/api/v1
• Format : JSON uniquement
• Authentification : Bearer Token (JWT) dans le header Authorization

3.3.2 Endpoints - Authentification

POST /auth/login

Description : Authentifier un utilisateur

Request Body :

{
  "email": "john.doe@example.com",
  "password": "SecureP@ssw0rd"
}

Response Success (200) :

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "email": "john.doe@example.com",
    "role": "JOUEUR",
    "must_change_password": false
  }
}

Response Error (401) :

{
  "detail": "Email ou mot de passe incorrect",
  "attempts_remaining": 3
}

Response Locked (403) :

{
  "detail": "Compte bloqué",
  "locked_until": "2025-10-18T15:30:00",
  "minutes_remaining": 28
}

POST /auth/change-password

Description : Changer son mot de passe

Authentification : Requise

Request Body :

{
  "current_password": "OldP@ssw0rd",
  "new_password": "NewSecureP@ssw0rd123!",
  "confirm_password": "NewSecureP@ssw0rd123!"
}

Response Success (200) :

{
  "message": "Mot de passe modifié avec succès"
}

POST /auth/logout

Description : Déconnecter l'utilisateur

Authentification : Requise

3.3.3 Endpoints - Joueurs

GET /players

Description : Liste tous les joueurs (Admin uniquement)

Authentification : Admin

Response (200) :

{
  "players": [
    {
      "id": 1,
      "first_name": "John",
      "last_name": "Doe",
      "company": "Tech Corp",
      "license_number": "L123456",
      "birth_date": "1990-05-15",
      "photo_url": null,
      "has_account": true
    }
  ],
  "total": 1
}

GET /players/{id}

Description : Détails d'un joueur

Authentification : Requise

POST /players

Description : Créer un joueur (Admin uniquement)

Authentification : Admin

Request Body :

{
  "first_name": "John",
  "last_name": "Doe",
  "company": "Tech Corp",
  "license_number": "L123456",
  "email": "john.doe@example.com"
}

Validation :

• first_name: 2-50 caractères, lettres et espaces
• last_name: 2-50 caractères, lettres et espaces
• company: 2-100 caractères
• license_number: Format LXXXXXX (unique)
• email: Format email valide (unique)

PUT /players/{id}

Description : Modifier un joueur (Admin uniquement)

DELETE /players/{id}

Description : Supprimer un joueur (Admin uniquement)

Condition : Le joueur ne doit appartenir à aucune équipe active

3.3.4 Endpoints - Équipes

GET /teams

Description : Liste toutes les équipes

Query Params :

• pool_id (optional): Filtrer par poule
• company (optional): Filtrer par entreprise

Response (200) :

{
  "teams": [
    {
      "id": 1,
      "company": "Tech Corp",
      "players": [
        {
          "id": 1,
          "first_name": "John",
          "last_name": "Doe"
        },
        {
          "id": 2,
          "first_name": "Jane",
          "last_name": "Smith"
        }
      ],
      "pool": {
        "id": 1,
        "name": "Poule A"
      }
    }
  ],
  "total": 1
}

POST /teams

Description : Créer une équipe (Admin uniquement)

Request Body :

{
  "company": "Tech Corp",
  "player1_id": 1,
  "player2_id": 2,
  "pool_id": 1
}

Validations :

• Les deux joueurs doivent appartenir à la même entreprise
• Chaque joueur ne peut être que dans une équipe par saison
• player1_id ≠ player2_id

PUT /teams/{id}

Description : Modifier une équipe (Admin uniquement)

Condition : Aucun match joué

DELETE /teams/{id}

Description : Supprimer une équipe (Admin uniquement)

Condition : Aucun match joué

3.3.5 Endpoints - Poules

GET /pools

Description : Liste toutes les poules

Response (200) :

{
  "pools": [
    {
      "id": 1,
      "name": "Poule A",
      "teams_count": 6,
      "teams": [...]
    }
  ]
}

POST /pools

Description : Créer une poule (Admin uniquement)

Request Body :

{
  "name": "Poule A",
  "team_ids": [1, 2, 3, 4, 5, 6]
}

Validation :

• Exactement 6 équipes
• Nom unique

PUT /pools/{id}

Description : Modifier une poule (Admin uniquement)

Condition : Aucun match joué dans la poule

DELETE /pools/{id}

Description : Supprimer une poule (Admin uniquement)

Condition : Aucun match joué dans la poule

3.3.6 Endpoints - Événements

GET /events

Description : Liste tous les événements

Query Params :

• start_date (optional): Date de début (YYYY-MM-DD)
• end_date (optional): Date de fin (YYYY-MM-DD)
• month (optional): Mois spécifique (YYYY-MM)

Response (200) :

{
  "events": [
    {
      "id": 1,
      "event_date": "2025-11-15",
      "event_time": "19:30",
      "matches": [
        {
          "id": 1,
          "court_number": 1,
          "team1": {...},
          "team2": {...},
          "status": "A_VENIR"
        }
      ]
    }
  ]
}

POST /events

Description : Créer un événement (Admin uniquement)

Request Body :

{
  "event_date": "2025-11-15",
  "event_time": "19:30",
  "matches": [
    {
      "court_number": 1,
      "team1_id": 1,
      "team2_id": 2
    },
    {
      "court_number": 2,
      "team1_id": 3,
      "team2_id": 4
    }
  ]
}

Validations :

• event_date >= aujourd'hui
• event_time format HH:MM
• 1 à 3 matchs par événement
• Pas de piste en double pour le même événement
• Une équipe ne peut jouer qu'un match par événement

PUT /events/{id}

Description : Modifier un événement (Admin uniquement)

DELETE /events/{id}

Description : Supprimer un événement (Admin uniquement)

Condition : Tous les matchs doivent avoir le statut A_VENIR

3.3.7 Endpoints - Matchs

GET /matches

Description : Liste des matchs

Query Params :

• upcoming: true pour les 30 prochains jours
• team_id: Filtrer par équipe
• status: Filtrer par statut
• my_matches: true pour les matchs de l'utilisateur connecté

Response (200) :

{
  "matches": [
    {
      "id": 1,
      "event": {
        "date": "2025-11-15",
        "time": "19:30"
      },
      "court_number": 1,
      "team1": {
        "id": 1,
        "company": "Tech Corp",
        "players": [...]
      },
      "team2": {
        "id": 2,
        "company": "Innov Ltd",
        "players": [...]
      },
      "status": "A_VENIR",
      "score_team1": null,
      "score_team2": null
    }
  ],
  "total": 1
}

POST /matches

Description : Créer un match (Admin uniquement)

PUT /matches/{id}

Description : Modifier un match (Admin uniquement)

Request Body (exemple - mise à jour du score) :

{
  "status": "TERMINE",
  "score_team1": "6-4, 6-3",
  "score_team2": "4-6, 3-6"
}

Validation du score :

• Format : "X-Y, X-Y" ou "X-Y, X-Y, X-Y"
• Chaque set : vainqueur >= 6 jeux
• Si 7-X : X <= 5
• 7-6 autorisé (tie-break)

DELETE /matches/{id}

Description : Supprimer un match (Admin uniquement)

Condition : Statut = A_VENIR

3.3.8 Endpoints - Résultats

GET /results/my-results

Description : Résultats de l'utilisateur connecté

Authentification : Joueur

Response (200) :

{
  "results": [
    {
      "match_id": 1,
      "date": "2025-10-15",
      "opponents": {
        "company": "Innov Ltd",
        "players": ["Alice Martin", "Bob Dupont"]
      },
      "score": "6-4, 6-3",
      "result": "VICTOIRE",
      "court_number": 1
    }
  ],
  "statistics": {
    "total_matches": 10,
    "wins": 7,
    "losses": 3,
    "win_rate": 70.0
  }
}

GET /results/rankings

Description : Classement général des entreprises

Response (200) :

{
  "rankings": [
    {
      "position": 1,
      "company": "Tech Corp",
      "matches_played": 10,
      "wins": 8,
      "losses": 2,
      "points": 24,
      "sets_won": 18,
      "sets_lost": 6
    }
  ]
}

3.3.9 Endpoints - Profil

GET /profile/me

Description : Profil de l'utilisateur connecté

Authentification : Requise

Response (200) :

{
  "user": {
    "id": 1,
    "email": "john.doe@example.com",
    "role": "JOUEUR"
  },
  "player": {
    "id": 1,
    "first_name": "John",
    "last_name": "Doe",
    "company": "Tech Corp",
    "license_number": "L123456",
    "birth_date": "1990-05-15",
    "photo_url": "/uploads/profile_1.jpg"
  }
}

PUT /profile/me

Description : Modifier son profil

Request Body :

{
  "first_name": "John",
  "last_name": "Doe",
  "birth_date": "1990-05-15",
  "email": "john.doe@newemail.com"
}

POST /profile/me/photo

Description : Upload photo de profil

Content-Type : multipart/form-data

Max size : 2MB

Formats : .jpg, .jpeg, .png

DELETE /profile/me/photo

Description : Supprimer la photo de profil

3.3.10 Endpoints - Administration

POST /admin/accounts/create

Description : Créer un compte pour un joueur

Authentification : Admin

Request Body :

{
  "player_id": 1,
  "role": "JOUEUR"
}

Response (201) :

{
  "message": "Compte créé avec succès",
  "email": "john.doe@example.com",
  "temporary_password": "T3mp@ryP@ss2025!Xy",
  "warning": "Ce mot de passe ne sera affiché qu'une seule fois"
}

POST /admin/accounts/{user_id}/reset-password

Description : Réinitialiser le mot de passe d'un utilisateur

Authentification : Admin

Response (200) :

{
  "message": "Mot de passe réinitialisé",
  "temporary_password": "N3wT3mp@ryP@ss!",
  "warning": "Ce mot de passe ne sera affiché qu'une seule fois"
}

3.4 Formats et Contraintes

3.4.1 Formats de dates et heures

3.4.2 Formats de validation

3.4.3 Codes de statut HTTP

4. Exigences de Sécurité

4.1 Authentification et Autorisation

4.1.1 JWT (JSON Web Tokens)

Configuration obligatoire :

• Algorithme : HS256
• Secret : Généré aléatoirement, stocké en variable d'environnement
• Durée de validité : 24 heures
• Payload minimum :
  • sub: user_id
  • email: email de l'utilisateur
  • role: rôle de l'utilisateur
  • exp: timestamp d'expiration

Implémentation :

# Exemple Python avec PyJWT
import jwt
from datetime import datetime, timedelta

def create_access_token(user_id: int, email: str, role: str) -> str:
    payload = {
        "sub": user_id,
        "email": email,
        "role": role,
        "exp": datetime.utcnow() + timedelta(hours=24)
    }
    return jwt.encode(payload, SECRET_KEY, algorithm="HS256")

4.1.2 Protection des routes

Middleware d'authentification :

• Vérifier la présence du token dans le header Authorization: Bearer {token}
• Valider le token (signature, expiration)
• Extraire les informations utilisateur
• Retourner 401 si token invalide ou absent

Middleware d'autorisation :

• Vérifier que le rôle de l'utilisateur correspond aux permissions requises
• Retourner 403 si permissions insuffisantes

4.2 Protection contre les attaques

4.2.1 Injection SQL

Exemple correct :

# ✅ CORRECT - Utilisation de l'ORM
user = db.query(User).filter(User.email == email).first()

# ❌ INTERDIT - Requête SQL brute
user = db.execute(f"SELECT * FROM users WHERE email = '{email}'")

4.2.2 XSS (Cross-Site Scripting)

Protection côté backend :

• Sanitization de toutes les entrées textuelles
• Échappement des caractères spéciaux HTML
• Headers de sécurité :
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • Content-Security-Policy

Protection côté frontend :

• Utilisation de v-text au lieu de v-html dans VueJS
• Validation des données avant affichage
• Pas d'eval() ou d'exécution de code dynamique

Exemple de sanitization :

import bleach

def sanitize_input(text: str) -> str:
    # Supprime tous les tags HTML
    return bleach.clean(text, tags=[], strip=True)

4.2.3 CSRF (Cross-Site Request Forgery)

Protection :

• Utilisation de tokens JWT (inclus dans les headers, pas dans les cookies)
• Vérification de l'origin des requêtes
• Header SameSite=Strict si utilisation de cookies

4.2.4 Brute Force (Anti-bot)

Algorithme :

    CREATE TABLE login_attempts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT NOT NULL,
    attempts_count INTEGER DEFAULT 0,
    last_attempt TIMESTAMP,
    locked_until TIMESTAMP NULL
);
1. Tentative de connexion reçue
2. Vérifier dans login_attempts si l'email est bloqué
   - Si locked_until > maintenant : retourner 403 avec temps restant
3. Vérifier les credentials
   - Si invalides :
     * Incrémenter attempts_count
     * Si attempts_count >= 5 :
       - Définir locked_until = maintenant + 30 minutes
     * Retourner 401 avec tentatives restantes
   - Si valides :
     * Réinitialiser attempts_count à 0
     * Retourner le token

5. Spécifications des Tests

5.1 Tests Unitaires (Backend Python)

5.1.1 Framework et organisation

Framework : Pytest

Structure :

tests/
├── conftest.py              # Fixtures globales
├── test_auth.py             # Tests authentification
├── test_players.py          # Tests joueurs
├── test_teams.py            # Tests équipes
├── test_matches.py          # Tests matchs
├── test_events.py           # Tests événements
├── test_security.py         # Tests sécurité
└── test_validation.py       # Tests validation

5.1.2 Couverture minimale requise

Commande pour mesurer la couverture :

pytest --cov=app --cov-report=html --cov-report=term

5.1.3 Exemple de test

# tests/test_auth.py
import pytest
from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_login_success(test_db, test_user):
    """Test connexion avec credentials valides"""
    response = client.post("/api/v1/auth/login", json={
        "email": "test@example.com",
        "password": "ValidP@ssw0rd123"
    })
    
    assert response.status_code == 200
    data = response.json()
    assert "access_token" in data
    assert data["user"]["email"] == "test@example.com"
    assert data["user"]["role"] == "JOUEUR"

def test_login_invalid_password(test_db, test_user):
    """Test connexion avec mot de passe invalide"""
    response = client.post("/api/v1/auth/login", json={
        "email": "test@example.com",
        "password": "WrongPassword"
    })
    
    assert response.status_code == 401
    data = response.json()
    assert "attempts_remaining" in data

def test_brute_force_protection(test_db, test_user):
    """Test blocage après 5 tentatives échouées"""
    # Faire 5 tentatives échouées
    for i in range(5):
        response = client.post("/api/v1/auth/login", json={
            "email": "test@example.com",
            "password": "WrongPassword"
        })
        assert response.status_code == 401
    
    # La 6ème tentative doit être bloquée
    response = client.post("/api/v1/auth/login", json={
        "email": "test@example.com",
        "password": "ValidP@ssw0rd123"
    })
    
    assert response.status_code == 403
    data = response.json()
    assert "locked_until" in data
    assert "minutes_remaining" in data

5.2 Tests End-to-End (Cypress ou autre)

5.2.1 Exemple Configuration Cypress

Installation :

npm install --save-dev cypress

Structure :

cypress/
├── e2e/
│   ├── auth.cy.js           # Tests authentification
│   ├── player.cy.js         # Tests joueur
│   ├── admin.cy.js          # Tests admin
│   └── navigation.cy.js     # Tests navigation
├── fixtures/
│   └── users.json           # Données de test
└── support/
    └── commands.js          # Commandes custom

5.2.2 Exemple de test Cypress

// cypress/e2e/auth.cy.js

describe('Authentification', () => {
  beforeEach(() => {
    cy.visit('http://localhost:5173')
  })

  it('Affiche la page de login', () => {
    cy.contains('Se connecter').should('be.visible')
    cy.get('input[type="email"]').should('be.visible')
    cy.get('input[type="password"]').should('be.visible')
  })

  it('Connexion avec credentials valides', () => {
    cy.get('input[type="email"]').type('joueur@example.com')
    cy.get('input[type="password"]').type('ValidP@ssw0rd123')
    cy.get('button[type="submit"]').click()
    
    // Vérifier la redirection
    cy.url().should('include', '/dashboard')
    cy.contains('Bienvenue').should('be.visible')
  })

  it('Connexion échoue avec mauvais mot de passe', () => {
    cy.get('input[type="email"]').type('joueur@example.com')
    cy.get('input[type="password"]').type('WrongPassword')
    cy.get('button[type="submit"]').click()
    
    // Vérifier le message d'erreur
    cy.contains('Email ou mot de passe incorrect').should('be.visible')
    cy.contains('tentatives restantes').should('be.visible')
  })

  it('Bloque le compte après 5 tentatives échouées', () => {
    // Faire 5 tentatives
    for (let i = 0; i < 5; i++) {
      cy.get('input[type="email"]').clear().type('joueur@example.com')
      cy.get('input[type="password"]').clear().type('WrongPassword')
      cy.get('button[type="submit"]').click()
      cy.wait(500)
    }
    
    // Vérifier le blocage
    cy.contains('Compte bloqué').should('be.visible')
    cy.contains('minutes').should('be.visible')
  })
})

5.3 Tests de Sécurité OWASP (Bonus)

5.3.1 OWASP Top 10

Tests recommandés :

5.3.2 Checklist de sécurité

□ Les mots de passe sont-ils hashés avec bcrypt?
□ Les tokens JWT expirent-ils correctement?
□ Les entrées utilisateur sont-elles sanitizées?
□ Le mécanisme anti-brute force fonctionne-t-il?
□ Les rôles sont-ils correctement vérifiés?
□ Les messages d'erreur ne divulguent-ils pas d'informations sensibles?
□ Les fichiers uploadés sont-ils validés?
□ Les headers de sécurité sont-ils présents?
□ HTTPS est-il forcé en production?
□ Les secrets sont-ils dans des variables d'environnement?

6. Livrables et Évaluation

6.1 Livrables attendus

6.1.1 Code source

Contenu obligatoire :

• Code source complet (backend + frontend)
• Fichier README.md détaillé
• Requirements.txt (Python) et package.json (Node)
• Base de données SQLite
• Tests unitaires et E2E (code applicatif + cahier de recette détaillé)
• Rapports d'anomalie (rapport de bug)

6.1.2 Rapport

Format :

Structure du rapport :

1. Introduction
   • Présentation du projet
   • Objectifs
2. Architecture
   • Schéma d'architecture
   • Choix technologiques
   • Modèle de données
3. Fonctionnalités implémentées
   • Description détaillée
   • Screenshots
4. Sécurité
   • Mesures implémentées
   • Tests de sécurité
   • Vulnérabilités identifiées et corrigées
5. Tests
   • Stratégie de test
   • Couverture
   • Résultats
6. Difficultés rencontrées
7. Améliorations possibles
8. Conclusion

7. Annexes

7.1 Kit de démarrage

Un kit de démarrage est fourni avec ce cahier des charges. Il contient :

• Structure backend FastAPI avec authentification JWT fonctionnelle
• Structure frontend VueJS avec routing configuré
• Base de données SQLite initialisée
• Page d'accueil et page de login
• README complet pour le lancement

7.2 Commandes utiles

7.2.1 Backend

# Installation
cd backend
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows
pip install -r requirements.txt

# Lancement
uvicorn app.main:app --reload --port 8000

# Tests
pytest
pytest --cov=app --cov-report=html

# Migrations (si Alembic utilisé)
alembic revision --autogenerate -m "description"
alembic upgrade head

7.2.2 Frontend

# Installation
cd frontend
npm install

# Lancement dev
npm run dev

# Build production
npm run build

# Tests E2E
npx cypress open
npx cypress run

7.3 Variables d'environnement

Fichier backend/.env :

# Database
DATABASE_URL=sqlite:///./padel_corpo.db

# Security
SECRET_KEY=your-secret-key-here-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440

# CORS
ALLOWED_ORIGINS=http://localhost:5173

# Upload
UPLOAD_DIR=./uploads
MAX_UPLOAD_SIZE=2097152

Fichier frontend/.env :

VITE_API_BASE_URL=http://localhost:8000/api/v1

7.4 Ressources recommandées

7.4.1 Documentation officielle

• FastAPI : https://fastapi.tiangolo.com/
• VueJS 3 : https://vuejs.org/
• SQLAlchemy : https://docs.sqlalchemy.org/
• Pytest : https://docs.pytest.org/
• Cypress : https://docs.cypress.io/
• OWASP Top 10 : https://owasp.org/www-project-top-ten/

7.4.2 Tutoriels utiles

• JWT Authentication avec FastAPI
• Vue Router pour SPA
• SQLAlchemy ORM best practices
• Writing effective Pytest tests
• Cypress E2E testing guide

7.5 Exemples de wireframes

7.5.1 Page de login

┌─────────────────────────────────────────┐
│                                         │
│           🎾 CORPO PADEL                │
│                                         │
│     ┌─────────────────────────────┐    │
│     │  Email                      │    │
│     │  ________________________   │    │
│     │                             │    │
│     │  Mot de passe               │    │
│     │  ________________________   │    │
│     │                             │    │
│     │      [ Se connecter ]       │    │
│     │                             │    │
│     │  Tentatives restantes: 5    │    │
│     └─────────────────────────────┘    │
│                                         │
└─────────────────────────────────────────┘

7.5.2 Planning (vue joueur)

┌─────────────────────────────────────────┐
│  🏠 Accueil | 📅 Planning | ⚽ Matchs   │
│  📊 Résultats | 👤 Profil               │
├─────────────────────────────────────────┤
│                                         │
│  PLANNING NOVEMBRE 2025                 │
│                                         │
│  [<]  NOVEMBRE 2025  [>]                │
│                                         │
│  L  M  M  J  V  S  D                    │
│              1  2  3                    │
│  4  5  6  7  8 [9] 10                   │
│  11 12 13 14 ●15 16 17                  │
│  18 19 20 ●22 23 24                     │
│  25 26 27 28 29 30                      │
│                                         │
│  ● = Événements planifiés               │
│                                         │
│  DÉTAILS DU 15 NOVEMBRE                 │
│  ┌───────────────────────────────────┐ │
│  │ 19:30 - Piste 1                   │ │
│  │ Tech Corp vs Innov Ltd            │ │
│  └───────────────────────────────────┘ │
│                                         │
└─────────────────────────────────────────┘

7.5.3 Administration

┌─────────────────────────────────────────┐
│  ADMINISTRATION                         │
├─────────────────────────────────────────┤
│                                         │
│  [Joueurs] [Équipes] [Poules] [Comptes]│
│                                         │
│  GESTION DES JOUEURS                    │
│                                         │
│  [+ Nouveau joueur]        🔍 Recherche │
│                                         │
│  ┌─────────────────────────────────────┐│
│  │ Nom      Prénom   Entreprise  📝 🗑 ││
│  ├─────────────────────────────────────┤│
│  │ Dupont   Jean     Tech Corp   ✏️ ❌ ││
│  │ Martin   Alice    Innov Ltd   ✏️ ❌ ││
│  │ Durand   Bob      StartCo     ✏️ ❌ ││
│  └─────────────────────────────────────┘│
│                                         │
│  Total: 3 joueurs                       │
│                                         │
└─────────────────────────────────────────┘

7.6 Règles métier récapitulatives

    # Application Corpo Padel
    
    ## Description
    Application de gestion de tournois corporatifs de padel.
    
    ## Prérequis
    - Python 3.11+
    - Node.js 18+
    - SQLite 3
    
    ## Installation
    
    ### Backend
    ```bash
    cd backend
    python -m venv venv
    
    # Linux/Mac
    source venv/bin/activate
    
    # Windows
    venv\Scripts\activate
    
    pip install -r requirements.txt
    ```
    
    ### Frontend
    ```bash
    cd frontend
    npm install
    ```
    
    ## Configuration
    
    ### Backend
    Créer un fichier `.env` dans le dossier backend :
    ```
    DATABASE_URL=sqlite:///./padel_corpo.db
    SECRET_KEY=votre-cle-secrete-ici
    ```
    
    ### Frontend
    Créer un fichier `.env` dans le dossier frontend :
    ```
    VITE_API_BASE_URL=http://localhost:8000/api/v1
    ```
    
    ## Lancement
    
    ### Backend
    ```bash
    cd backend
    uvicorn app.main:app --reload --port 8000
    ```
    
    Le backend sera accessible sur http://localhost:8000
    
    ### Frontend
    ```bash
    cd frontend
    npm run dev
    ```
    
    Le frontend sera accessible sur http://localhost:5173
    
    ## Comptes de test
    
    ### Administrateur
    - Email: admin@padel.com
    - Mot de passe: Admin@2025!
    
    ### Joueur
    - Email: joueur@padel.com
    - Mot de passe: Joueur@2025!
    
    ## Tests
    
    ### Tests unitaires backend
    ```bash
    cd backend
    pytest
    pytest --cov=app --cov-report=html
    ```
    
    ### Tests E2E
    ```bash
    cd frontend
    npx cypress open
    ```
    
    ## Structure du projet
    
    ```
    .
    ├── backend/
    │   ├── app/
    │   │   ├── api/          # Routes API
    │   │   ├── models/       # Modèles SQLAlchemy
    │   │   ├── schemas/      # Schémas Pydantic
    │   │   ├── services/     # Logique métier
    │   │   └── main.py       # Point d'entrée
    │   └── tests/
    ├── frontend/
    │   ├── src/
    │   │   ├── components/   # Composants Vue
    │   │   ├── views/        # Pages
    │   │   ├── router/       # Configuration routing
    │   │   └── App.vue
    │   └── cypress/
    └── README.md
    ```
    
    ## Fonctionnalités implémentées
    
    - ✅ Authentification JWT avec anti-brute force
    - ✅ Gestion des joueurs, équipes, poules
    - ✅ Planning et matchs
    - ✅ Résultats et classements
    - ✅ Administration
    - ✅ Profils utilisateurs
    
    ## Sécurité
    
    - Hashing des mots de passe avec bcrypt
    - Protection anti-brute force (5 tentatives max)
    - Validation des entrées (Pydantic + frontend)
    - Protection XSS
    - Utilisation exclusive de l'ORM (pas de SQL brut)
    - Headers de sécurité
    
    ## Auteurs
    [Vos noms]
    
    ## Licence
    Projet pédagogique - Formation Ingénieur
    ```
    

7.9 Checklist avant rendu

    □ L'application démarre correctement en suivant le README
    □ Tous les comptes de test fonctionnent
    □ Le mécanisme anti-brute force est opérationnel
    □ Les mots de passe sont hashés dans la base
    □ Toutes les validations sont en place
    □ Les tests unitaires passent (couverture >= 70%)
    □ Les tests E2E passent
    □ Le rapport PDF est complet (10-15 pages)
    □ Le code est commenté et propre
    □ Les fichiers .env ne contiennent pas de vraies valeurs sensibles
    □ Le fichier .gitignore exclut venv/, node_modules/, .env
    □ Les requirements.txt et package.json sont à jour
    □ Aucune erreur console dans le frontend
    □ Aucune erreur dans les logs backend
    □ Les messages d'erreur sont clairs pour l'utilisateur
    □ La navigation entre les pages fonctionne
    □ Les rôles sont correctement vérifiés
    □ Les routes protégées ne sont pas accessibles sans auth
    □ Le classement se calcule correctement
    □ Les filtres de matchs fonctionnent
    □ Les formulaires ont une validation temps réel
    

7.10 Calendrier suggéré (12h)

backend/
├── app/
│   ├── api/
│   │   ├── auth.py          ✅ Routes d'authentification
│   │   └── deps.py          ✅ Dépendances (get_current_user)
│   ├── core/
│   │   ├── config.py        ✅ Configuration
│   │   └── security.py      ✅ JWT + hashing
│   ├── models/
│   │   └── models.py        ✅ User + LoginAttempt
│   ├── schemas/
│   │   └── auth.py          ✅ Schémas Pydantic
│   ├── database.py          ✅ Configuration SQLAlchemy
│   └── main.py              ✅ Application FastAPI
├── tests/
│   ├── conftest.py          ✅ Fixtures
│   ├── test_auth.py         ✅ Tests authentification
│   ├── test_security.py     ✅ Tests sécurité
│   └── test_validation.py   ✅ Tests validation
├── .env.example
├── requirements.txt
└── README.md
            

frontend/
├── src/
│   ├── components/
│   │   └── NavBar.vue       ✅ Barre de navigation
│   ├── router/
│   │   └── index.js         ✅ Routing avec guards
│   ├── services/
│   │   └── api.js           ✅ Client Axios + intercepteurs
│   ├── stores/
│   │   └── auth.js          ✅ Store Pinia authentification
│   ├── views/
│   │   ├── HomePage.vue     ✅ Page d'accueil
│   │   └── LoginPage.vue    ✅ Page de connexion
│   ├── App.vue
│   └── main.js
├── cypress/
│   ├── e2e/
│   │   ├── auth.cy.js       ✅ Tests E2E auth
│   │   └── navigation.cy.js ✅ Tests navigation
│   └── support/
│       └── commands.js      ✅ Commandes custom
├── .env.example
├── package.json
└── README.md
            

git clone https://github.com/AndreyPividori/PolytechTours-PadelStarterKit.git
cd PolytechTours-PadelStarterKit

cd backend

# Créer l'environnement virtuel
python -m venv venv

# Activer l'environnement
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Installer les dépendances
pip install -r requirements.txt

# Configuration
cp .env.example .env

# Générer une SECRET_KEY
python -c "import secrets; print(secrets.token_urlsafe(32))"
# Copier la clé générée dans le fichier .env

# Initialiser la base de données
python -c "from app.database import init_db; init_db()"

# Lancer le serveur
uvicorn app.main:app --reload --port 8000

cd frontend

# Installer les dépendances
npm install

# Configuration
cp .env.example .env

# Lancer le serveur de développement
npm run dev

cd backend
source venv/bin/activate  # ou venv\Scripts\activate

# Lancer tous les tests
pytest

# Avec couverture de code
pytest --cov=app --cov-report=html

# Ouvrir le rapport de couverture
# Le fichier htmlcov/index.html contient le rapport détaillé

cd frontend

# Mode interactif (recommandé pour le développement)
npx cypress open

# Mode headless (pour CI/CD)
npx cypress run

# Linux/Mac
lsof -ti:8000 | xargs kill -9

# Windows
netstat -ano | findstr :8000
taskkill /PID <PID> /F

# Vérifier que l'environnement virtuel est activé
# Vous devriez voir (venv) dans votre terminal

pip install -r requirements.txt

ALLOWED_ORIGINS=http://localhost:5173

cd frontend
rm -rf node_modules package-lock.json
npm install

# Après avoir cloné le starter kit
cd PolytechTours-PadelStarterKit

# Supprimer le remote d'origine
git remote remove origin

# Ajouter votre remote
git remote add origin <url-de-votre-nouveau-repo>

# Créer une branche develop
git checkout -b develop

# Pousser sur votre repository
git push -u origin main
git push -u origin develop

# Créer une branche pour chaque fonctionnalité
git checkout develop
git checkout -b feature/gestion-joueurs

# Développer, tester, commiter
git add .
git commit -m "feat: ajout CRUD joueurs"

# Pousser la branche
git push origin feature/gestion-joueurs

# Merger dans develop après validation
git checkout develop
git merge feature/gestion-joueurs

git commit -m "feat: ajout de la gestion des équipes"
git commit -m "fix: correction bug anti-brute force"
git commit -m "test: ajout tests pour les matchs"