Aller au contenu

Les règles métier

Temps 3 · séance 1 · ~30 min

Les slides du chapitre (PDF)

  • Reconnaître une règle métier et la distinguer d'une règle de format et d'un droit.
  • Classer une règle métier dans l'une des trois familles : calcul, état, capacité ou unicité.
  • Écrire une règle dans le rapport, en une phrase et deux exemples chiffrés.
  • Placer la règle dans une méthode du modèle ou de l'enum, et l'appeler dans une transaction.
  • Tirer un test Pest de chaque exemple, et le voir échouer avant d'écrire la règle.

1. Douze places dans le bus

L'école organise une visite du Parlement européen. Le bus a douze places. Au secrétariat, la liste des inscrits tient sur une feuille de douze lignes. Quand la douzième ligne est remplie, la secrétaire écrit les noms suivants au dos, dans une liste d'attente.

Voici la même activité dans une petite application Laravel. Les étudiants s'inscrivent, et le secrétariat confirme chaque inscription. Le seeder crée la visite, onze inscriptions confirmées et deux en attente, celles de Yasmine El Idrissi et de Tom Lambert. Tinker lit l'activité :

php artisan tinker --execute='$a = App\Models\Activity::first(); echo $a->title, " · ", $a->confirmedCount(), "/", $a->capacity, " · complet : ", var_export($a->isFull(), true), PHP_EOL;'
Visite du Parlement européen · 11/12 · complet : false

Le secrétariat confirme Yasmine, et le bus est plein. Il confirme ensuite Tom. Dans la première version de l'application, rien ne l'en empêche : l'activité compte treize inscrits confirmés pour douze places. Le code n'a aucune erreur. Il ne connaît simplement pas la limite du bus.

Cette limite s'appelle une règle métier. C'est une contrainte qui vient du travail du client, pas de la technique. Elle resterait vraie si l'école gérait ses sorties avec une feuille et un crayon, comme aujourd'hui. Personne ne la devine en lisant le code de Laravel. Il faut la demander au client.

2. Trois familles de règles

Les règles métier se ressemblent d'un sujet à l'autre. La plupart entrent dans l'une de ces trois familles.

Une règle de calcul fixe un taux, un total ou un seuil. « Une activité payante coûte 8 € par personne, et 5 € pour un étudiant boursier. » « Chaque participant paie sa part du bus, 240 € divisés par le nombre d'inscrits confirmés. » La règle dit comment obtenir un chiffre, ou ce qui se passe quand un chiffre franchit une limite.

Une règle d'état dit ce qu'une donnée peut devenir, selon ce qu'elle est déjà. « Une inscription annulée ne se confirme plus. » « On ne passe à l'étape suivante que si la précédente est faite. » Une donnée passe d'un état à l'autre, et certains passages sont interdits.

Une règle de capacité ou d'unicité limite un nombre. « Pas plus de douze inscrits confirmés dans le bus. » « Un étudiant ne s'inscrit qu'une fois à la même activité. » La règle compte ce qui existe déjà avant d'accepter une ligne de plus.

Le Tamagotchi du temps 2 en avait déjà. Le solde ne descend jamais sous zéro et une jauge ne dépasse pas 100 : ce sont deux règles métier du jeu.

3. Format, droit, règle métier

Trois sortes de contrôles refusent une action, et les trois se confondent facilement. Voici trois refus possibles quand le secrétariat confirme une inscription.

Règle de format Droit Règle métier
Exemple Le statut envoyé est pending, confirmed ou cancelled. Seul le secrétariat confirme une inscription. Une activité de douze places n'accepte pas de treizième inscrit confirmé.
La réponse dépend de la valeur envoyée, seule la personne connectée les données déjà en base
Où elle s'écrit la Form Request la policy, appelée par Gate::authorize() une méthode du modèle ou de l'enum, appelée dans une transaction
Ce que voit l'utilisateur une erreur en français sous le champ la page 403 « Accès refusé » un message en français qui explique le refus
Comment on la teste assertSessionHasErrors() avec une valeur mal formée assertForbidden() avec le compte d'un autre rôle un test par exemple de la règle, accepté et refusé, et la base relue

La deuxième ligne du tableau sert à trancher. Pour classer une contrainte, demandez-vous de quoi dépend la réponse. Si la valeur envoyée suffit, c'est du format. Si la réponse change selon la personne connectée, c'est un droit. Si elle change selon ce qui est déjà en base, c'est une règle métier.

Le statut confirmed est bien formé. Le secrétariat a le droit de confirmer. Pourtant, la confirmation de Tom doit être refusée, parce que douze lignes sont déjà confirmées. Ni la Form Request ni la policy ne peuvent le voir.

À vous : classer cinq contraintes (5 min)

Pour chaque contrainte, dites si c'est une règle de format, un droit ou une règle métier, et pour une règle métier, sa famille.

  1. La date d'une activité est une date valide.
  2. Un étudiant ne voit que ses propres inscriptions.
  3. Un étudiant ne s'inscrit qu'une fois à la même activité.
  4. Une inscription confirmée peut encore être annulée, une inscription annulée ne revient plus.
  5. Une conférence gratuite pour les étudiants coûte 10 € aux visiteurs extérieurs.
  1. Format : la valeur seule suffit pour répondre.
  2. Droit : la réponse dépend de la personne connectée.
  3. Règle métier, unicité : il faut chercher en base une inscription existante.
  4. Règle métier, état : la réponse dépend du statut déjà enregistré.
  5. Règle métier, calcul : le prix se calcule selon la personne inscrite.

4. Écrire la règle dans le rapport

Dans votre rapport, chaque règle porte un numéro, R1, R2, et tient en une phrase suivie de deux exemples chiffrés : un cas accepté et un cas refusé. Comme pour les besoins du chapitre 1.05, voici la même règle écrite deux fois.

Mal écrit Bien écrit
Règle Il ne faut pas trop d'inscrits à une activité. R1. Une activité n'a jamais plus d'inscriptions confirmées que de places.
Exemple accepté Quand il reste de la place, ça passe. Activité de 12 places, 11 inscriptions confirmées : le secrétariat confirme la suivante, l'activité compte 12 inscriptions confirmées.
Exemple refusé Sinon, on bloque. Activité de 12 places, 12 inscriptions confirmées : la confirmation suivante est refusée avec le message « L'activité est complète, les 12 places sont prises. », l'inscription reste en attente.

La colonne de gauche dit « trop » et « de la place » sans chiffre. Deux personnes la liraient de deux façons, et personne ne peut écrire un test à partir d'elle. La colonne de droite donne la capacité, le nombre de lignes déjà en base, l'action et ce que l'application répond. Chaque exemple devient un test, presque mot pour mot.

Choisissez des exemples à la frontière. Onze et douze, pas trois et cinquante. Une règle se trompe d'abord d'une unité, et un test à la frontière le voit.

5. Où la règle vit dans le code

L'application d'inscription a deux modèles. Activity porte un titre, une date et une capacité, capacity. Registration relie un utilisateur à une activité et porte un statut, status. Le secrétariat change le statut par la route PATCH /inscriptions/{registration}.

Le modèle répond à la question

La règle R1 pose une question à l'activité : êtes-vous complète ? Cette question s'écrit dans le modèle, app/Models/Activity.php, avec la relation registrations() :

public function confirmedCount(): int
{
    return $this->registrations()
        ->where('status', RegistrationStatus::Confirmed)
        ->count();
}

public function isFull(): bool
{
    return $this->confirmedCount() >= $this->capacity;
}

confirmedCount() compte les inscriptions confirmées dans la base. isFull() les compare à la capacité. La règle est écrite une fois, avec le nom du métier. Le contrôleur, la page de l'activité et un futur tableau de bord posent la même question avec $activity->isFull().

L'enum connaît les passages permis

La règle R2 est une règle d'état : une inscription annulée ne se confirme plus. Le statut est une enum, app/Enums/RegistrationStatus.php, que le modèle Registration utilise comme cast. Une enum PHP peut porter des méthodes, et c'est l'endroit naturel d'une règle qui ne dépend que du statut :

enum RegistrationStatus: string
{
    case Pending = 'pending';
    case Confirmed = 'confirmed';
    case Cancelled = 'cancelled';

    public function nextStatuses(): array
    {
        return match ($this) {
            self::Pending => [self::Confirmed, self::Cancelled],
            self::Confirmed => [self::Cancelled],
            self::Cancelled => [],
        };
    }

    public function canBecome(self $next): bool
    {
        return in_array($next, $this->nextStatuses(), true);
    }
}

nextStatuses() donne, pour chaque statut, les statuts vers lesquels on peut passer. canBecome() répond à la question de R2 pour un passage précis. L'enum a aussi une méthode label() qui donne le libellé en français. Tinker les affiche toutes :

php artisan tinker --execute='use App\Enums\RegistrationStatus; foreach (RegistrationStatus::cases() as $s) { echo $s->label(), " -> ", implode(", ", array_map(fn ($n) => $n->label(), $s->nextStatuses())) ?: "rien", PHP_EOL; }'
En attente -> Confirmée, Annulée
Confirmée -> Annulée
Annulée -> rien

Le contrôleur l'appelle dans une transaction

app/Http/Controllers/RegistrationController.php passe les trois contrôles du tableau, dans l'ordre. La Form Request UpdateRegistrationRequest valide le format avant que la méthode commence. Gate::authorize() vérifie le droit. Les deux règles métier viennent ensuite :

public function update(UpdateRegistrationRequest $request, Registration $registration): RedirectResponse
{
    Gate::authorize('update', $registration);

    $next = $request->enum('status', RegistrationStatus::class);

    DB::transaction(function () use ($registration, $next) {
        // Read the activity and the registration again, locked until the end.
        $activity = Activity::lockForUpdate()->findOrFail($registration->activity_id);
        $registration = Registration::lockForUpdate()->findOrFail($registration->id);

        // R2: a registration only moves to an allowed status.
        if (! $registration->status->canBecome($next)) {
            throw ValidationException::withMessages([
                'status' => "Une inscription « {$registration->status->label()} » ne peut pas passer à « {$next->label()} ».",
            ]);
        }

        // R1: never more confirmed registrations than places.
        if ($next === RegistrationStatus::Confirmed && $activity->isFull()) {
            throw ValidationException::withMessages([
                'status' => "L'activité est complète, les {$activity->capacity} places sont prises.",
            ]);
        }

        $registration->update(['status' => $next]);
    });

    Inertia::flash('toast', ['type' => 'success', 'message' => 'Inscription mise à jour.']);

    return to_route('activities.show', $registration->activity_id);
}

$request->enum() lit le champ status et le transforme en cas de l'enum. Le reste vous est connu depuis le chapitre 2.09. Deux personnes du secrétariat peuvent confirmer la douzième place au même instant. Sur MySQL ou MariaDB, la transaction et le verrou font attendre la seconde, qui relit le compte et reçoit le refus. Le refus lève une ValidationException : la transaction est annulée, et le message s'affiche sous le bouton « Confirmer », dans le <InputError> du champ status.

La policy, elle, ne contient que le droit. RegistrationPolicy::update() renvoie $user->is_staff, et rien sur les places. Si la règle des places était dans la policy, le secrétariat recevrait une page 403 « Accès refusé » quand le bus est plein. Il a pourtant le droit de confirmer : c'est le bus qui n'a plus de place.

6. Un test par exemple

Les deux exemples de R1 deviennent deux tests, dans tests/Feature/RegistrationRulesTest.php. La fabrique RegistrationFactory a un état confirmed(), écrit comme le draft() du chapitre 1.17. Un beforeEach() en tête du fichier crée une activité de douze places et un compte du secrétariat :

beforeEach(function () {
    $this->secretariat = User::factory()->create(['is_staff' => true]);
    $this->activity = Activity::factory()->create(['capacity' => 12]);
});

test('R1 accepted: 11 confirmed out of 12 places, the next one is confirmed', function () {
    Registration::factory()->count(11)->confirmed()->for($this->activity)->create();
    $next = Registration::factory()->for($this->activity)->create();

    $this->actingAs($this->secretariat)
        ->patch("/inscriptions/{$next->id}", ['status' => 'confirmed'])
        ->assertRedirect("/activites/{$this->activity->id}")
        ->assertSessionHasNoErrors();

    expect($next->fresh()->status)->toBe(RegistrationStatus::Confirmed);
    expect($this->activity->confirmedCount())->toBe(12);
});

test('R1 refused: 12 confirmed out of 12 places, the next one stays pending', function () {
    Registration::factory()->count(12)->confirmed()->for($this->activity)->create();
    $next = Registration::factory()->for($this->activity)->create();

    $this->actingAs($this->secretariat)
        ->from("/activites/{$this->activity->id}")
        ->patch("/inscriptions/{$next->id}", ['status' => 'confirmed'])
        ->assertRedirect("/activites/{$this->activity->id}")
        ->assertSessionHasErrors(['status' => 'L\'activité est complète, les 12 places sont prises.']);

    expect($next->fresh()->status)->toBe(RegistrationStatus::Pending);
    expect($this->activity->confirmedCount())->toBe(12);
});

beforeEach() tourne avant chaque test du fichier. for($this->activity) rattache les inscriptions créées à cette activité. from() indique la page d'où part la requête : un refus renvoie vers elle, comme votre <Form> dans le navigateur. Les deux tests relisent la base à la fin. Un refus qui affiche le bon message mais confirme quand même serait pris.

Écrivez les tests avant la règle. Sans les deux if du contrôleur, lancez-les :

php artisan test --filter=R1
   FAIL  Tests\Feature\RegistrationRulesTest
  ✓ R1 accepted: 11 confirmed out of 12 places, the next one is confirmed        0.44s
  ⨯ R1 refused: 12 confirmed out of 12 places, the next one stays pending        0.05s
  ────────────────────────────────…
   FAILED  Tests\Feature\RegistrationRulesTest > R1 refused: 12 confirmed out of 12 places, the next one stays pendi…
  Session is missing expected key [errors].
Failed asserting that false is true.

  at tests\Feature\RegistrationRulesTest.php:36
  …
  ➜  36▕         ->assertSessionHasErrors(['status' => 'L\'activité est complète, les 12 places sont prises.']);
  …
  Tests:    1 failed, 1 passed (8 assertions)

Le test accepté passe déjà, puisque l'application accepte tout. Seul le test refusé prouve que la règle existe. « Session is missing expected key [errors] » dit qu'aucune erreur n'a été rangée dans la session : la treizième confirmation est passée. Ajoutez les deux if, puis relancez :

   PASS  Tests\Feature\RegistrationRulesTest
  ✓ R1 accepted: 11 confirmed out of 12 places, the next one is confirmed        0.45s
  ✓ R1 refused: 12 confirmed out of 12 places, the next one stays pending        0.04s

  Tests:    2 passed (11 assertions)

Le fichier complet teste aussi R2, l'enum, le droit et le format :

php artisan test tests/Feature/RegistrationRulesTest.php
   PASS  Tests\Feature\RegistrationRulesTest
  ✓ R1 accepted: 11 confirmed out of 12 places, the next one is confirmed        0.44s
  ✓ R1 refused: 12 confirmed out of 12 places, the next one stays pending        0.04s
  ✓ R2 refused: a cancelled registration cannot be confirmed                     0.03s
  ✓ the status values a registration can move to                                 0.02s
  ✓ a student cannot confirm a registration                                      0.04s
  ✓ an unknown status is refused                                                 0.03s

  Tests:    6 passed (21 assertions)

Pour votre projet, l'exigence O1 suit la même forme. La règle de votre sujet, écrite dans le rapport avec ses deux exemples, donne deux tests. Le cas refusé est celui que vous montrez à la présentation.

À retenir

  • Une règle métier vient du travail du client et resterait vraie sur papier : elle se demande au client, elle ne se devine pas.
  • Une contrainte qui dépend de la valeur envoyée est du format, de la personne connectée un droit, des données déjà en base une règle métier.
  • Une règle s'écrit en une phrase et deux exemples chiffrés à la frontière, un accepté et un refusé.
  • La règle vit dans une méthode du modèle ou de l'enum, et le contrôleur l'appelle dans une transaction, sous verrou.
  • Chaque exemple devient un test Pest qui relit la base, et le test du cas refusé échoue tant que la règle manque.