abouba/api-plr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9ceaec5becab6c3dd62643029fcfa1599399dc3e
api-plr/README.md
Aboubacar SANGARE 9ceaec5bec done all the implementations of each parts yet
2025-09-25 13:22:35 +00:00

12 KiB
Raw Blame History

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
  2. Installation & tests
  3. Conventions API
  4. Flux typique (Happy Path)
  5. Entités & Endpoints
  6. Règles métier & validations
  7. Recettes de test
  8. 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

git clone https://github.com/<ton-org>/<ton-repo>.git
cd <ton-repo>

Compilation & lancement

./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
  3. 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 : 
    {
  "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 : 
    [
  { "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 : 
    { "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 ): !!!