317 lines
12 KiB
Markdown
317 lines
12 KiB
Markdown
# 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 ): !!! |