UC-04 — Réservation repas

Acteur : Porteur de carte (ou parent pour un enfant) But : Réserver un repas pour une date ultérieure

Trigger

Un porteur souhaite réserver un repas pour une date future.

Préconditions

• Le porteur possède une carte active
• Le repas existe dans le catalogue et est disponible à la date
• La date respecte les règles (préavis, horizon, heure limite)

Postconditions

• Une réservation est créée (pending) et le montant est débité immédiatement
• Le porteur peut annuler avant l'échéance (remboursement automatique)

Endpoints

1. Vérifier la disponibilité

GET /api/v1/reservations/availability?date=2025-06-15&site_id=uuid-site

2. Créer la réservation

POST /api/v1/reservations
Content-Type: application/json
Idempotency-Key: <uuid-v4>

{
  "card_holder_id": "uuid-porteur",
  "for_date": "2025-06-15",
  "items": [
    { "product_id": "uuid-produit", "quantity": 1 }
  ],
  "menu_id": "uuid-menu",
  "notes": "Sans sucre"
}

3. Suivre / lister

GET /api/v1/reservations

4. Annuler

PATCH /api/v1/reservations/{id}/status
Idempotency-Key: <uuid-v4>
Content-Type: application/json

{
  "status": "cancelled",
  "reason": "Enfant absent"
}

Flow

sequenceDiagram
    participant Porteur
    participant App
    participant API
    participant DB

    Porteur->>App: "Réserver un repas pour le 15 juin"
    App->>API: GET /reservations/availability?date=2025-06-15
    API-->>App: {can_reserve: true, products: [...]}

    App->>API: POST /reservations
    API->>DB: Vérifie disponibilité + solde
    API->>DB: INSERT reservation (pending) + débit carte
    API-->>App: {reservation, new_balance}
    App->>Porteur: "Réservation confirmée"

    Note over Porteur: Plus tard...

    Porteur->>App: Annuler
    App->>API: PATCH /reservations/{id}/status {status: cancelled}
    API->>DB: Remboursement + restauration stock
    API-->>App: {reservation, refund_transaction_id}

Exemple de réponse (création)

{
  "id": "uuid",
  "card_holder_id": "uuid",
  "product_id": "uuid",
  "quantity": 1,
  "total_price_cents": 1200,
  "total_price_formatted": "1 200 FCFA",
  "for_date": "2025-06-15",
  "status": "pending",
  "can_be_cancelled": true,
  "card_transaction_id": "uuid",
  "success": true,
  "currency": "XOF"
}

Permissions

Permission	Description
reservation.create	Créer une réservation
reservation.cancel	Annuler (déclenche le remboursement)

Erreurs

error_code	Description
Validation	Date hors préavis/horizon, produit indisponible
NotFound	Porteur, produit ou menu introuvable
Forbidden	Contrôle IDOR (porteur ≠ card_holder_id)

Voir Réservations et Disponibilité.