Modèle de données

Fonctionnement

erDiagram
    "Entreprise" ||--o{ "Contact" : "emploie"
    "Entreprise" |o--o{ "Demande d'offre" : "demande"
    "Courtier" |o--o{ "Demande d'offre" : "apporte"
    "Courtier de l'annuaire" |o--o{ "Demande d'offre" : "est cité dans"
    "Demande d'offre" ||--o{ "Offre" : "produit"
    "Offre" ||--o| "Police" : "devient"
    "Entreprise" ||--o{ "Police" : "est assurée par"
    "Courtier" |o--o{ "Police" : "gère"
    "Police" ||--o{ "Période de garantie" : "se découpe en"
    "Période de garantie" ||--o{ "Paiement" : "facture"
    "Paiement" ||--o{ "Ligne de commission" : "génère"
    "Police" |o--o{ "Ligne de bordereau" : "génère"

Une entreprise peut avoir plusieurs contacts et plusieurs polices. Une demande d’offre peut produire plusieurs offres, mais une offre donne au plus une police.

La demande d’offre est le dossier : elle porte le statut, l’entreprise, le contact et le courtier. Ses offres chiffrées lui sont rattachées.
La police est créée à partir de l’offre acceptée. Chaque période de garantie est conservée à part. Un avenant, un renouvellement ou une régularisation est aussi une période (types : affaire nouvelle, renouvellement, avenant, régularisation). Une période n’est jamais modifiée, on en ajoute une nouvelle.
Un paiement pointe vers l’offre, la période de garantie et l’abonnement Stripe. Les remboursements sont enregistrés à part.
Chaque paiement encaissé ouvre une ligne de commission (commission ou reprise de commission), regroupée dans le relevé mensuel du courtier. Voir Commissions et bordereau.
Les lignes de bordereau reflètent les mouvements de police pour l’assureur, en centimes entiers. Une ligne n’est pas liée à un rapport : elle va dans le rapport du mois de sa date d’événement. Elle peut exister sans police.
Un courtier appartient à un cabinet (une entreprise). L’annuaire de courtiers est une liste importée : une entrée n’est liée à un courtier que si le cabinet rejoint la plateforme.
Les utilisateurs se connectent comme contact (client), courtier ou administrateur. Voir Portails et courtiers.

Règles et pièges

Les instantanés sont figés à l’émission. La police garde une copie de ce que le client a signé : conditions de prix (numéro d’offre, formule, taux de taxe, frais), réponses au risque, entités affiliées, garanties, et versions des documents contractuels. Les changements ultérieurs de tarif, de questions ou de documents ne modifient jamais une police existante. Voir Tarification, conditions figées sur la police et instantané des réponses au risque.
Les périodes sont en ajout seul. Ne modifiez jamais une période passée, voir renouvellement par période de police.
Suppression logique. Polices, périodes, paiements, entreprises, contacts, offres, demandes d’offre, courtiers, utilisateurs, communications courtier et lignes et relevés de commission sont masqués, pas effacés. Les écrans de suppression ne les montrent plus, mais une recherche doit les inclure explicitement pour les retrouver. Un numéro d’offre reste unique même si l’offre est supprimée.
Garde-fous de suppression. Un paiement synchronisé avec Stripe ou finalisé ne se supprime pas : on le rembourse ou on l’annule. Le contact principal d’une entreprise ne se supprime pas tant qu’il reste d’autres contacts.

Pourquoi : les suppressions définitives cassaient les relevés, paiements et polices liés. Les données sont donc masquées plutôt qu’effacées, et les suppressions dangereuses sont refusées.

Entreprise partagée. Une entreprise est partagée entre courtiers : chaque courtier ne voit que ses propres contacts et dossiers, voir isolation courtier sur société partagée.
Notifications Stripe traitées une fois. Chaque notification de Stripe est enregistrée, pour qu’un même message n’ait d’effet qu’une fois, voir webhooks Stripe tolérants à l’ordre.
Neutralité produit. Chaque donnée porte son produit : le cœur ne suppose pas le cyber, voir cœur neutre vis-à-vis du produit.

Correspondance technique

Nom courant	Table
Entreprise, Contact	`companies`, `contacts`
Demande d’offre, Offre	`quote_requests`, `quotes`
Police, Période de garantie	`policies`, `policy_periods`
Paiement, Remboursement	`payments`, `payment_refunds`
Courtier, Courtier de l’annuaire	`brokers`, `directory_brokers`
Ligne de commission, Relevé de commission	`broker_commission_lines`, `broker_commission_statements`
Ligne de bordereau, Rapport de bordereau	`bordereau_lines`, `bordereau_reports`
Notifications Stripe traitées	`stripe_webhook_events`

À retenir pour le SQL brut et les sauvegardes :

Les identifiants sont des UUID, sauf pour les lignes de bordereau, les notifications Stripe, les réponses de registre, les prospects, les médias et les tables Cashier. Les pays utilisent leur code à 2 lettres.
Les tables techniques du framework commencent par _ (_jobs, _job_batches, _failed_jobs, _activity_log). Celles de Cashier, Telescope et des médias non.
Les paiements et les polices stockent des décimaux, le bordereau et les lignes de commission des centimes entiers.

Où dans le code

database/migrations
app/Models (traits dans app/Models/Concerns)
app/Services/PolicyService.php (ce qui est figé à l’émission)