done all the implementations of each parts yet

2025-09-25 13:22:35 +00:00
parent 4b7b8649d3
commit 9ceaec5bec
42 changed files with 2816 additions and 136 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,317 @@
+# Documentation API — PMU PLR
+
+> **API de gestion des paris hippiques (PMU)**  
+> Ce projet implémente la logique complète de gestion de **chevaux**, **courses**, **paris**, **résultats** et **gains**.
+
+---
+
+## Table des matières
+
+1. [Présentation générale](#présentation-générale)
+2. [Installation & tests](#installation--tests)
+   - [Prérequis](#prérequis)
+   - [Clonage du projet](#clonage-du-projet)
+   - [Compilation & lancement](#compilation--lancement)
+   - [Tests avec Postman](#tests-avec-postman)
+3. [Conventions API](#conventions-api)
+4. [Flux typique (Happy Path)](#flux-typique-happy-path)
+5. [Entités & Endpoints](#entités--endpoints)
+   - [Chevaux](#1-chevaux)
+   - [Courses & Inscriptions](#2-courses--inscriptions)
+   - [Paris](#3-paris)
+   - [Résultats](#4-résultats)
+   - [Gains](#5-gains)
+6. [Règles métier & validations](#règles-métier--validations)
+7. [Recettes de test](#recettes-de-test)
+   - [A) Flux complet](#a-flux-complet-end-to-end)
+   - [B) Validation & contraintes](#b-validation--contraintes)
+   - [C) Cas d’ex æquo (Dead-Heat)](#c-cas-dex-æquo-dead-heat)
+   - [D) Gestion NP/DQ](#d-gestion-npdq)
+   - [E) Idempotence du règlement](#e-idempotence-du-règlement)
+8. [Exemples de payloads](#exemples-de-payloads)
+
+---
+
+## Présentation générale
+
+Cette API gère le cycle complet du **Pari Mutuel Urbain (PMU)** :
+
+- Gestion des **courses** (création, planification, mise à jour, clôture).
+- Inscription et gestion des **chevaux** (insertion, participation, non-partant, disqualification).
+- Création et mise à jour des **paris** (tous types : simple, couple, trio, quarté, quinté, multi, etc.).
+- Déclaration des **résultats officiels**, avec gestion des ex æquo (Dead-Heat).
+- Calcul et attribution des **gains** selon les règles PMU.
+
+---
+
+## Installation & tests
+
+### Prérequis
+
+- **Java 17+**
+- **Maven**
+- **PostgreSQL** (base `pmu`)
+- **Postman** (pour importer la collection fournie)
+
+### Clonage du projet
+
+```bash
+git clone https://github.com/<ton-org>/<ton-repo>.git
+cd <ton-repo>
+```
+
+### Compilation & lancement
+
+```bash
+./mvnw clean install
+./mvnw spring-boot:run
+```
+
+Le serveur démarre sur :
+👉 http://localhost:8080
+
+### Tests avec Postman
+
+Importer la collection :
+1. PMU PLR API - Full Test Collection.postman_collection.json
+2. Définir la variable d’environnement baseUrl = http://localhost:8080
+2. Exécuter les requêtes dans l’ordre :
+    - Création course → Ajout chevaux → Paris → Résultat → Règlement → Vérification gains.
+
+## Conventions API
+
+- Base URL : {{baseUrl}}
+
+- Format JSON
+
+- Enums :
+    - CourseStatue = **PLANIFIEE | EN_COURS | CLOTUREE | ANNULEE**
+    - PariType = **SIMPLE_GAGNANT | SIMPLE_PLACE | COUPLE_GAGNANT | COUPLE_ORDRE | TRIO | TRIO_ORDRE | TIERCE | QUARTE | QUINTE | QUINTE_PLUS | MULTI**
+
+- Dead-Heat : plusieurs chevaux peuvent partager le même rang.
+
+## Flux typique (Happy Path)
+
+1. Créer une course (statut = PLANIFIEE).
+2. Inscrire les chevaux (simple ou bulk).
+3. Créer des paris (tant que la course est PLANIFIEE).
+4. Déclarer les résultats officiels (Dead-Heat permis).
+5. Fixer le Numéro+ pour Quinté+.
+6. Régler la course (calcul des gains).
+7. Vérifier les rapports et gains.
+
+## Entités & Endpoints
+### 1. Chevaux
+
+Endpoints pour la gestion des données des chevaux, indépendamment de leur inscription à une course.
+
+| Méthode | Endpoint | Description |
+| :--- | :--- | :--- |
+| `GET` | `/api/chevaux` | Lister tous les chevaux. |
+| `GET` | `/api/chevaux/{id}` | Obtenir les détails d'un cheval. |
+| `POST` | `/api/chevaux` | Créer un nouveau cheval. |
+| `PUT` | `/api/chevaux/{id}` | Modifier les informations d'un cheval existant. |
+| `DELETE` | `/api/chevaux/{id}` | Supprimer un cheval de la base de données. |
+
+---
+
+### 2. Courses & Inscriptions
+
+Gérer la création et la modification des courses et des inscriptions de chevaux.
+
+| Méthode | Endpoint | Description |
+| :--- | :--- | :--- |
+| `GET` | `/api/courses` | Lister toutes les courses. |
+| `GET` | `/api/courses/{id}` | Obtenir les détails d'une course spécifique. |
+| `GET` | `/api/courses/{STATUS: CourseStatue}` | Obtenir les courses spécifique par status (CourseStatue). |
+| `POST` | `/api/courses` | Créer une nouvelle course. |
+| `PUT` | `/api/courses/{id}` | Modifier une course existante. |
+| `DELETE` | `/api/courses/{id}` | Supprimer une course. |
+| `POST` | `/api/courses/chevaux` | Ajouter un seul cheval à une course. |
+| `POST` | `/api/courses/chevaux` | Ajouter un cheval à une course en une seule requête. |
+| `POST` | `/api/courses/chevaux/bulk` | Ajouter plusieurs chevaux à une course en une seule requête. |
+| `GET` | `/api/courses/{id}/chevaux` | Lister les chevaux inscrites à une course. |
+| `PUT` | `/api/courses/cheval-course/{id}/scratch?value={true\|false}` | (Dé)marquer un cheval comme non-partant (NP). |
+| `PUT` | `/api/courses/cheval-course/{id}/disqualify?value={true\|false}` | (Dé)qualifier un cheval d'une course. |
+| `DELETE` | `/api/courses/cheval-course/{id}` | Supprimer un cheval d'une course quelqu'en soit la course. |
+| `DELETE` | `/api/courses/cheval-course/{id}` | Supprimer un cheval d'une course quelqu'en soit la course. |
+
+---
+
+### 3. Paris
+
+Points d'accès pour la création, la modification et la gestion des paris.
+
+| Méthode | Endpoint | Description |
+| :--- | :--- | :--- |
+| `POST` | `/api/paris` | Créer un nouveau pari. |
+| `GET` | `/api/paris/{id}` | Obtenir le détail d’un pari spécifique. |
+| `PUT` | `/api/paris/{id}` | Modifier un pari existant. |
+| `DELETE` | `/api/paris/{id}` | Supprimer un pari. |
+| `GET` | `/api/paris` | Lister tous les paris (avec filtres possibles). |
+| `GET` | `/api/paris/course/{courseId}` | Obtenir la liste de tous les paris pour une course spécifique. |
+| `POST` | `/api/paris/course/settle/{courseId}` | Régler tous les paris d'une course après officialisation des résultats. |
+| `GET` | `/api/paris/course/report/{courseId}` | Générer un rapport détaillé des paris d'une course. |
+| `GET` | `/api/gains/pari/{pariId}` | Vérifier le gain associé à un pari donné. |
+| `GET` | `/api/gains/course/{courseId}` | Lister tous les gains générés pour une course après règlement. |
+
+---
+
+### 4. Résultats
+
+Gérer les résultats officiels et le classement d'une course.
+
+| Méthode | Endpoint | Description |
+| :--- | :--- | :--- |
+| `POST` | `/api/resultats` | Créer un résultat pour une course. |
+| `GET` | `/api/resultats` | Lister tous les résultats. |
+| `GET` | `/api/resultats/course/{courseId}` | Récupérer le résultat d’une course. |
+| `PUT` | `/api/resultats/course/{courseId}` | Mettre à jour le résultat d’une course. |
+| `DELETE` | `/api/resultats/course/{courseId}` | Supprimer le résultat d’une course. |
+| `GET` | `/api/resultats/course/{courseId}/chevaux` | Lister les chevaux avec leurs rangs. |
+| `POST` | `/api/resultats/course/{courseId}/chevaux` | Ajouter un cheval dans le résultat. |
+| `PUT` | `/api/resultats/course/{courseId}/chevaux/{chevalId}` | Mettre à jour ou insérer le rang d’un cheval. |
+| `DELETE` | `/api/resultats/course/{courseId}/chevaux/{chevalId}` | Supprimer un cheval du résultat. |
+| `PATCH` | `/api/resultats/course/{courseId}/numero-plus` | Fixer le **Numéro+ gagnant** (Quinté+). |
+| `PUT` | `/api/resultats/course/{courseId}/numero-plus/draw` | Tirer au sort automatiquement le Numéro+. |
+
+
+---
+
+### 5. Gains
+
+Points d'accès pour la vérification des gains et la génération de rapports.
+| Méthode | Endpoint | Description |
+| :--- | :--- | :--- |
+| `GET` | `/api/gains/course/{courseId}` | Obtenir les gains de tous les paris d’une course. |
+| `GET` | `/api/gains/pari/{pariId}` | Obtenir les détails des gains pour un pari donné. |
+| `POST` | `/api/paris/course/settle/{courseId}` | Régler et distribuer les gains d’une course. |
+
+
+
+## Règles métier & validations
+
+Les règles métier et les validations appliquées aux différentes étapes du cycle de vie d'une course, des paris aux résultats.
+
+---
+
+### 1. Gestion des courses
+
+* **Course PLANIFIÉE :** Il s'agit de la seule phase pendant laquelle il est possible d'enregistrer des paris. Toute tentative de créer un pari en dehors de ce statut sera rejetée.
+* **Résultats créés :** Une fois que les résultats officiels sont enregistrés, le statut de la course est automatiquement mis à jour à **CLÔTURÉE**.
+
+---
+
+### 2. Validations des paris
+
+Les règles suivantes sont appliquées pour garantir la validité des paris :
+
+* **Positions obligatoires :** Pour les paris ordonnés, toutes les positions doivent être renseignées.
+* **Doublons interdits :** Un ticket de pari ne peut pas contenir de doublons de cheval ou de position.
+* **Dead-Heat :** Le système autorise les ex æquo (chevaux arrivant à égalité) dans les résultats.
+* **Quinté+ :** Chaque ticket de Quinté+ se voit attribuer un **Numéro+** aléatoire au moment de la création du pari.
+
+
+---
+
+
+## Recettes de test
+
+Ce document détaille les différentes recettes de test pour valider le bon fonctionnement de l'API.
+
+---
+
+### A) Flux complet (end-to-end)
+
+1.  Créer une course.
+2.  Inscrire des chevaux à la course.
+3.  Placer des paris sur la course.
+4.  Déclarer les résultats officiels.
+5.  Régler la course (calcul des gains).
+6.  Vérifier les gains générés pour les paris gagnants.
+
+---
+
+### B) Validation & contraintes
+
+* **Pari avec cheval en double :** Tenter de placer un pari contenant deux fois le même cheval. Le système doit retourner une erreur **400 (Bad Request)**.
+* **Pari avec cheval NP :** Tenter de placer un pari incluant un cheval marqué comme non-partant (NP). Le système doit rejeter le pari.
+
+---
+
+### C) Cas d’ex æquo (Dead-Heat)
+
+* Déclarer deux chevaux ayant le même rang (par exemple, `rang=1`).
+* Vérifier que le calcul du pari de type **SIMPLE_GAGNANT** fonctionne correctement pour l'un ou l'autre des chevaux à égalité.
+
+---
+
+### D) Gestion NP/DQ
+
+* **Réintégration (NP) :** Envoyer une requête `PUT` avec `scratch?value=false` pour réintégrer un cheval précédemment non-partant.
+* **Requalification (DQ) :** Envoyer une requête `PUT` avec `disqualify?value=false` pour requalifier un cheval précédemment disqualifié.
+
+---
+
+### E) Idempotence du règlement
+
+* Tenter de régler une même course à deux reprises (`POST /api/paris/course/settle/{courseId}`). Les résultats du calcul des gains doivent être **identiques** à chaque exécution.
+
+---
+
+## Exemples de payloads
+### 1. Données du pari
+
+* **Endpoint :** `POST /api/paris`
+* **Description :** Création d'un pari TRIO.
+* **Corps de la requête :**
+    ```json
+    {
+      "courseId": 4,
+      "pariType": "TRIO",
+      "mise": 3000.00,
+      "bettorRef": "punter-C",
+      "selections": [
+        { "chevalId": 7, "position": 1 },
+        { "chevalId": 9, "position": 2 },
+        { "chevalId": 10, "position": 3 }
+      ]
+    }
+    ```
+
+---
+
+### 2. Données des résultats
+
+* **Endpoint :** `POST /api/resultats`
+* **Description :** Enregistrement des résultats officiels de la course.
+* **Corps de la requête :**
+    ```json
+    [
+      { "chevalId": 9, "rang": 1 },
+      { "chevalId": 7, "rang": 2 },
+      { "chevalId": 10, "rang": 3 }
+    ]
+    ```
+
+---
+
+### 3. Numéro+ (non pertinent pour ce pari)
+
+* **Endpoint :** `PATCH /api/resultats/course/{courseId}/numero-plus`
+* **Description :** Enregistrement du Numéro+ pour la course.
+* **Corps de la requête :**
+    ```json
+    { "numeroPlusGagnant": "654321" }
+    ```
+* **Note :** Le Numéro+ n'a pas d'impact sur le pari de type TRIO, mais est inclus pour documenter le flux complet de règlement d'une course.
+
+---
+
+### 4. Résultat attendu
+
+Le pari est **gagnant** si les trois chevaux sélectionnés figurent parmi les trois premiers de l'arrivée, quel que soit l'ordre. Dans ce cas, les chevaux `7`, `9` et `10` sont bien dans les trois premières positions du classement officiel. Le pari doit être réglé comme un gain.
+
+------
+
+Bon testing ): !!!