# 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 ): !!!