Cycle de vie des offres et machine d’etat

Chaque offre dans QuoteNode suit un cycle de vie strict et valide. Le systeme impose les transitions autorisees et rejette toute tentative de passage vers un etat invalide.

Definitions des statuts

Statut	Description	Editable	Terminal
DRAFT	L’offre est en preparation. Elle n’est pas encore visible par le client.	Oui	Non
SENT	L’offre a ete livree au client par email ou via lien public.	Non	Non
OPENED	Le client a consulte le lien public au moins une fois.	Non	Non
NEGOTIATION	Le client a repondu avec une question ou une contre-proposition.	Non	Non
ACCEPTED	Le client a confirme la commande.	Non	Oui
REJECTED	Le client a refuse l’offre.	Non	Oui
EXPIRED	La periode de validite est depassee sans decision.	Non	Oui
ARCHIVED	Archivee manuellement par le commercial.	Non	Oui

Regles de transition

DRAFT ──────────► SENT
  │                 │
  │                 ▼
  │              OPENED
  │                 │
  │                 ├──► NEGOTIATION
  │                 │        │
  │                 ├──► ACCEPTED (terminal)
  │                 ├──► REJECTED (terminal)
  │                 └──► EXPIRED  (terminal)
  │
  └──► ARCHIVED (terminal)

Transitions valides

• DRAFT → SENT — quand le commercial envoie l’offre par email ou genere un lien public
• SENT → OPENED — quand le client ouvre le lien public pour la premiere fois (automatique)
• OPENED → NEGOTIATION — quand le client envoie un message de reponse
• OPENED → ACCEPTED — quand le client clique sur “Accept” sur la page publique
• OPENED → REJECTED — quand le client clique sur “Decline” sur la page publique
• SENT/OPENED/NEGOTIATION → EXPIRED — quand valid_until est depasse (automatique, via job planifie)
• DRAFT → ARCHIVED — quand le commercial archive manuellement une offre non envoyee
• NEGOTIATION → ACCEPTED — quand le client accepte apres negociation
• NEGOTIATION → REJECTED — quand le client rejette apres negociation

Transitions invalides (rejetees par la machine d’etat)

• SENT → DRAFT (impossible d’annuler un envoi)
• ACCEPTED → quoi que ce soit (etat terminal)
• REJECTED → quoi que ce soit (etat terminal)
• EXPIRED → quoi que ce soit (etat terminal, mais clonable)
• ARCHIVED → quoi que ce soit (etat terminal)

Ce qui se passe a chaque transition

DRAFT → SENT

1. Le systeme verifie que l’offre contient au moins une ligne
2. Un snapshot immuable est cree (document JSON capturant tout l’etat de l’offre)
3. En cas d’envoi email : l’email est mis en file avec piece jointe PDF et/ou lien public
4. En cas de generation de lien public : un token aleatoire 256 bits est cree (seul le hash SHA-256 est stocke)
5. Le statut passe a SENT
6. Un evenement timeline est ecrit sur le client
7. Une entree est ajoutee au journal d’audit

SENT → OPENED

1. Le client accede a l’URL publique
2. Le hash du token est retrouve en base
3. Le statut passe a OPENED (uniquement lors de la premiere ouverture ; les suivantes incrementent le compteur)
4. Un web event est enregistre : timestamp, IP anonymisable, user agent, pays (GeoIP)
5. Le commercial recoit une notification si elle est configuree

OPENED → ACCEPTED

1. Le client clique sur “Accept” dans la page publique
2. Le rate limiting et la detection de bots sont verifies
3. Les donnees optionnelles d’intention de commande sont capturees (nom, email, societe, message)
4. Le statut passe a ACCEPTED
5. Le commercial recoit une notification immediate
6. Un evenement timeline est ajoute

Snapshots

Un snapshot est un enregistrement complet et immuable de l’offre au moment ou elle a ete envoyee :

• donnees client (nom de societe, adresse, contact)
• toutes les lignes d’offre (produits, quantites, prix, remises, taux de TVA)
• totaux calcules (sous-total, transport, ventilation TVA, total general)
• taux de change utilise (pour les offres multi-devises)
• configuration branding (logo, couleurs, conditions commerciales)
• reglages de modele (colonnes visibles, mode d’affichage des prix)

Les snapshots ne sont jamais modifies. Si l’offre est renvoyee apres modification, une nouvelle version de snapshot est creee avec un numero de version incremente.

Les PDF sont toujours generes a partir des snapshots, jamais a partir des donnees d’offre vivantes. Cela garantit que le PDF correspond exactement a ce qui a ete presente au client.

Piste d’audit

Chaque transition de statut ecrit une entree immuable dans le journal d’audit contenant :

• l’ID utilisateur et le role de l’acteur (ou “system” pour les transitions automatiques)
• l’adresse IP source
• le statut precedent et le nouveau statut
• le timestamp cote serveur
• un commentaire optionnel (par exemple la raison d’un rejet)

Le journal d’audit est append-only. Les entrees ne peuvent etre ni modifiees, ni supprimees, ni tronquees, y compris par les administrateurs.

Operations sur les offres terminales

Les offres terminales (ACCEPTED, REJECTED, EXPIRED, ARCHIVED) ne peuvent pas etre modifiees, mais elles peuvent servir de base a de nouvelles offres :

• Clone — cree un nouveau DRAFT avec les memes lignes et les memes prix
• Extend Validity — clone avec une nouvelle date d’expiration
• Update Prices — clone et recalcule a partir des prix catalogue et taux FX courants
• Use as Template — clone sans client ni prix, comme modele vierge

Ces operations creent toujours une nouvelle offre avec un nouvel ID et le statut DRAFT. L’offre d’origine reste intacte.