Transformez une idée en spec que votre IA de code respecte.

Produit. Application web de réservation pour coachs sportifs indépendants : le coach publie disponibilités et tarifs, le client réserve et paie en ligne sans compte, puis reçoit un SMS de rappel J-1. Objectif : moins de no-shows et moins de relances manuelles.

Ce qui est décidé

• Marché France, EUR, interface en français, web responsive Europe/Paris (D-01, D-09).
• Paiement intégral via Stripe Checkout, versement direct au coach via Connect Express (D-02, D-03).
• Pas de compte client : email et mobile (06/07), lien de gestion par email (D-08).
• Annulation remboursée jusqu'à 24 h avant la séance, aucune commission au MVP (D-07, D-10).
• Rappel SMS Twilio J-1, strictement transactionnel, sans offre promotionnelle (D-05, D-06).

Ce qui reste une hypothèse à vérifier avant de coder

• Frais Stripe Connect et modèle de charge : qui absorbe les frais de remboursement (D-03, RM-09).
• Remboursement automatique impossible si le solde du coach est négatif : à tester sur compte test.
• SMS de service sans consentement (D-06) : validation juridique RGPD/CNIL avant production.

Corrections de la relecture

Comment utiliser ce dossier

1. Contexte : donner à l'outil cette page, puis Cadrage, modèle de données (§4) et règles métier (RM), en précisant que les corrections EC-xx prévalent.
2. Plan : lui faire suivre §6 dans l'ordre des jalons, de J0 à J3 (tranche « réserver et payer » P-01), une tâche T-xx à la fois.
3. Validation : pour chaque tâche, exiger les CA liés et la « preuve de fin » (tests Vitest/Playwright, services externes mockés) avant de passer à la suivante.

Statuts (liste unique)

Besoins

Règles métier

Valeurs par défaut en H. Toutes les heures sont en Europe/Paris (D-09).

Table de décision : annulation et remboursement (RM-07, RM-08, RM-15)

Critères d'acceptation

Questions ouvertes (hypothèses actuelles)

Stack retenue

Composants

• Web/API : pages publiques, espace coach, endpoints de réservation et de gestion par jeton.
• Webhook Stripe : vérifie la signature, déduplique (evenement_stripe), confirme ou rembourse (RM-06).
• Worker : expire les verrous (RM-04), envoie les rappels (RM-10), clôture les séances (RM-15).
• Adaptateurs : Stripe, Twilio, email, derrière des interfaces simulables.

Modèle de données (PostgreSQL)

CREATE EXTENSION IF NOT EXISTS btree_gist;  -- requis pour l'exclusion (RM-05)
CREATE EXTENSION IF NOT EXISTS pgcrypto;

CREATE TABLE coach (
  id                 uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  email              text NOT NULL,
  mot_de_passe_hash  text NOT NULL,
  nom_affiche        text NOT NULL,
  slug               text NOT NULL,                       -- lien public partageable (MVP-04)
  stripe_account_id  text,
  connect_complet    boolean NOT NULL DEFAULT false,      -- RM-14
  cree_le            timestamptz NOT NULL DEFAULT now(),
  CONSTRAINT coach_slug_format CHECK (slug ~ '^[a-z0-9-]{3,50}$')
);
-- CA-31 : un email = un compte (insensible à la casse)
CREATE UNIQUE INDEX coach_email_uniq ON coach (lower(email));
CREATE UNIQUE INDEX coach_slug_uniq ON coach (slug);

CREATE TABLE seance_type (
  id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  coach_id        uuid NOT NULL REFERENCES coach(id) ON DELETE CASCADE,
  titre           text NOT NULL,
  duree_minutes   integer NOT NULL CHECK (duree_minutes BETWEEN 15 AND 240),
  prix_cents      integer NOT NULL CHECK (prix_cents > 0),   -- RM-06 : EUR, intégral
  lieu            text NOT NULL,
  actif           boolean NOT NULL DEFAULT true,             -- RM-12 : désactivation sans suppression
  cree_le         timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX seance_type_coach_idx ON seance_type (coach_id) WHERE actif;

-- Disponibilités hebdomadaires récurrentes (heure locale Europe/Paris, D-09)
CREATE TABLE disponibilite (
  id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  coach_id     uuid NOT NULL REFERENCES coach(id) ON DELETE CASCADE,
  jour_semaine smallint NOT NULL CHECK (jour_semaine BETWEEN 1 AND 7),  -- 1 = lundi
  heure_debut  time NOT NULL,
  heure_fin    time NOT NULL,
  CONSTRAINT disponibilite_plage CHECK (heure_fin > heure_debut)
);
CREATE INDEX disponibilite_coach_idx ON disponibilite (coach_id, jour_semaine);

CREATE TABLE date_bloquee (
  id        uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  coach_id  uuid NOT NULL REFERENCES coach(id) ON DELETE CASCADE,
  jour      date NOT NULL,
  UNIQUE (coach_id, jour)
);
-- RM-12 (refus du blocage si réservation CONFIRMEE ce jour) : contrôle applicatif, CA-25.

CREATE TABLE reservation (
  id                       uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  coach_id                 uuid NOT NULL REFERENCES coach(id),
  seance_type_id           uuid NOT NULL REFERENCES seance_type(id),
  client_nom               text NOT NULL,
  client_email             text NOT NULL,
  client_mobile_e164       text NOT NULL,
  debut                    timestamptz NOT NULL,
  fin                      timestamptz NOT NULL,
  prix_cents               integer NOT NULL CHECK (prix_cents > 0),   -- copie figée du prix
  statut                   text NOT NULL DEFAULT 'EN_ATTENTE_PAIEMENT',
  statut_paiement          text NOT NULL DEFAULT 'AUCUN',
  verrou_expire_le         timestamptz,                                -- RM-04 : créée + 15 min
  jeton_gestion            text NOT NULL DEFAULT encode(gen_random_bytes(32), 'hex'), -- RM-13 : 256 bits
  stripe_session_id        text,
  stripe_payment_intent_id text,
  cree_le                  timestamptz NOT NULL DEFAULT now(),
  mis_a_jour_le            timestamptz NOT NULL DEFAULT now(),
  annulee_le               timestamptz,

  CONSTRAINT reservation_statut_valide CHECK (statut IN
    ('EN_ATTENTE_PAIEMENT','CONFIRMEE','ANNULEE_CLIENT','ANNULEE_COACH','EXPIREE','TERMINEE')),
  CONSTRAINT reservation_paiement_valide CHECK (statut_paiement IN
    ('AUCUN','PAYE','REMBOURSE','ECHEC_REMBOURSEMENT')),
  CONSTRAINT reservation_plage CHECK (fin > debut),
  -- RM-11 : mobile français normalisé E.164
  CONSTRAINT reservation_mobile_e164 CHECK (client_mobile_e164 ~ '^\+33[67][0-9]{8}$'),
  CONSTRAINT reservation_email_format CHECK (client_email ~ '^[^@\s]+@[^@\s]+\.[^@\s]+$'),
  -- RM-04 : un verrou est obligatoire tant que le paiement est en attente
  CONSTRAINT reservation_verrou_requis CHECK (statut <> 'EN_ATTENTE_PAIEMENT' OR verrou_expire_le IS NOT NULL),
  -- RM-06 : CONFIRMEE implique un paiement capturé
  CONSTRAINT reservation_confirmee_payee CHECK (statut <> 'CONFIRMEE' OR statut_paiement = 'PAYE'),

  -- RM-01 + RM-05 : pas de chevauchement pour un même coach tant que la réservation
  -- est EN_ATTENTE_PAIEMENT ou CONFIRMEE ; la première écriture gagne (CA-06).
  CONSTRAINT reservation_pas_de_chevauchement EXCLUDE USING gist (
    coach_id WITH =,
    tstzrange(debut, fin, '[)') WITH &&
  ) WHERE (statut IN ('EN_ATTENTE_PAIEMENT','CONFIRMEE'))
);
CREATE UNIQUE INDEX reservation_jeton_uniq ON reservation (jeton_gestion);       -- RM-13
CREATE UNIQUE INDEX reservation_session_uniq ON reservation (stripe_session_id)
  WHERE stripe_session_id IS NOT NULL;
CREATE INDEX reservation_coach_debut_idx ON reservation (coach_id, debut DESC);  -- tableau de bord (BE-13)
CREATE INDEX reservation_expiration_idx ON reservation (verrou_expire_le)
  WHERE statut = 'EN_ATTENTE_PAIEMENT';                                          -- job RM-04
CREATE INDEX reservation_cloture_idx ON reservation (fin)
  WHERE statut = 'CONFIRMEE';                                                    -- job RM-15

-- Idempotence des webhooks Stripe (RM-06, CA-09)
CREATE TABLE evenement_stripe (
  id_evenement  text PRIMARY KEY,           -- evt_... : doublon = INSERT en conflit, sans effet
  type          text NOT NULL,
  recu_le       timestamptz NOT NULL DEFAULT now(),
  traite_le     timestamptz
);

-- Rappels SMS : au plus un par réservation (RM-10, CA-18)
CREATE TABLE rappel_sms (
  id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  reservation_id  uuid NOT NULL UNIQUE REFERENCES reservation(id) ON DELETE CASCADE, -- jamais de doublon
  envoi_prevu_le  timestamptz NOT NULL,     -- début - 24 h
  statut          text NOT NULL DEFAULT 'a_envoyer'
                  CHECK (statut IN ('a_envoyer','envoye','echec','annule')),
  tentatives      smallint NOT NULL DEFAULT 0 CHECK (tentatives BETWEEN 0 AND 2),  -- 1 essai + 1 retry à +10 min
  twilio_sid      text,
  derniere_erreur text,
  envoye_le       timestamptz
);
CREATE INDEX rappel_sms_a_envoyer_idx ON rappel_sms (envoi_prevu_le) WHERE statut = 'a_envoyer';

-- Journal des anomalies (RM-06 montant ≠ attendu, ECHEC_REMBOURSEMENT, échec SMS)
CREATE TABLE journal_anomalie (
  id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  reservation_id  uuid REFERENCES reservation(id) ON DELETE SET NULL,
  type            text NOT NULL,
  detail          jsonb NOT NULL DEFAULT '{}',
  cree_le         timestamptz NOT NULL DEFAULT now()
);

Garanties portées par la base

Contrôles applicatifs (hors base)

RM-02, RM-03 (délai min. 2 h, horizon 60 j), RM-07 et RM-08 (table de décision d'annulation), RM-12 (blocage de date) et RM-14 (connect_complet). Le job d'expiration libère le créneau en passant le statut à EXPIREE, ce qui sort la ligne de la contrainte d'exclusion.

Conventions : JSON sur HTTPS ; erreurs { "code", "message" } ; heures ISO 8601 en UTC, affichées en Europe/Paris (D-09). Session coach par cookie HttpOnly, Secure, SameSite=Lax H. Accès client par jeton de gestion (RM-13), sans compte.

API

Comportement structurant :

• API-14 : transaction unique. INSERT dans reservation (la contrainte reservation_pas_de_chevauchement tranche la concurrence, violation → 409), puis création de la session Checkout avec stripe_session_id. Si Stripe échoue, la ligne passe en EXPIREE.
• API-17 : INSERT dans evenement_stripe ; conflit sur id_evenement → sans effet. Montant ≠ prix_cents → pas de confirmation, ligne dans journal_anomalie. Réservation déjà EXPIREE → remboursement automatique, statut_paiement = REMBOURSE.
• API-11 / API-16 : mêmes transitions que la table de décision de la section 2 ; remboursement Stripe en échec → ECHEC_REMBOURSEMENT et anomalie journalisée.
• API-03 : l'événement Stripe account.updated (reçu par API-17) met à jour connect_complet.

Intégrations externes

Sécurité et données personnelles

1. Authentification coach : mot de passe haché argon2id ou bcrypt (mot_de_passe_hash), limitation des tentatives sur API-02, session expirante H.
2. Autorisation : toute requête coach filtre par coach_id de la session ; accès hors périmètre → 404 (CA-26). Jeton de gestion à 256 bits, 404 uniforme si inconnu (CA-27).
3. Paiement : aucune donnée de carte chez nous (Stripe Checkout). Webhook accepté uniquement avec signature valide ; clés Stripe, Twilio et Resend en variables d'environnement, jamais dans le dépôt.
4. Transport et entrées : HTTPS obligatoire, validation serveur de tous les champs (E.164, email), requêtes SQL paramétrées, limitation de débit sur API-13, API-14 et API-16 contre l'abus de verrous H.
5. Données personnelles (RGPD) : client = nom, email, mobile, minimisés à ce qui sert la séance. Hébergement UE, journaux sans mobile ni email en clair. Durée de conservation H : 3 ans après la séance, puis anonymisation. SMS strictement transactionnels (D-05, D-06).
6. Droits des personnes : procédure manuelle d'accès, rectification et effacement sur demande (MVP). Information et base légale (exécution du contrat) à afficher en E-02. À valider par le porteur du projet ; ce document n'est pas un avis juridique.

Hypothèses de plan H : un seul dépôt Next.js + PostgreSQL ; Stripe, Twilio et Resend sont isolés derrière des interfaces simulables (mocks en test) ; tests : Vitest (unitaire et intégration sur Postgres de test) et Playwright (bout en bout). La tranche verticale prioritaire est P-01 (réserver et payer) : elle est livrée dès le jalon J3. Chaque tâche suppose les corrections EC-xx intégrées (marquées « corrige EC-xx »).

Décisions de plan issues de la relecture

J0 — Socle (dépôt, base, outillage)

J1 — Compte coach et paiements activés

J2 — Séances et disponibilités

J3 — Tranche verticale : réserver et payer (P-01)

J4 — Notifications et gestion client

J5 — Espace coach : suivi et annulation

J6 — Durcissement et livraison

Couverture des critères d'acceptation

Les 32 CA sont couverts. Les T-13 et T-17 s'appuient sur rappel_sms créé à la confirmation (EC-02) ; l'ordre T-13 → T-17 → T-18 → T-20 respecte les dépendances.

Écarts

Hypothèses à vérifier en premier

• Frais de remboursement Stripe Connect (D-03, RM-09) : le coach les absorbe, avec risque de solde insuffisant et de remboursements bloqués ; vérifier la tarification Connect et le modèle de charge (destination vs direct) avant de coder.
• Remboursement automatique Stripe Connect sans solde coach : si le compte du coach est négatif, le remboursement peut échouer systématiquement ; tester sur compte test.
• SMS de service sans consentement (D-06) : la qualification « message de service » repose sur des sources de blogs ; faire valider par un juriste (RGPD/CNIL) avant la mise en production.