# CRM — modèle de données Entreprises, prospects, référentiel des pays. Le runtime **existe** : API Hono dans `src/`, 18 routes sous `/api/crm`, front React séparé. Le détail des endpoints, du déploiement et de la sécurité est dans [`../../docs/api.md`](../../docs/api.md), [`../../docs/deployment.md`](../../docs/deployment.md) et [`../../docs/security.md`](../../docs/security.md). ## Modèle de données ```mermaid erDiagram users ||--o{ password_reset_tokens : "possede" users ||--o{ organizations : "pilote" users ||--o{ contacts : "pilote" users ||--o{ deals : "pilote" users ||--o{ tasks : "assignee" users ||--o{ audit_logs : "trace" countries ||--o{ organizations : "situee" countries ||--o{ contacts : "situe" organizations ||--o{ contacts : "emploie" organizations ||--o{ deals : "concerne" contacts ||--o{ deals : "interlocuteur" pipeline_stages ||--o{ deals : "etape" pipeline_stages ||--o{ deal_stage_history : "transitions" deals ||--o{ deal_stage_history : "parcourt" deals ||--o{ activities : "genere" deals ||--o{ tasks : "genere" contacts ||--o{ activities : "genere" contacts ||--o{ tasks : "genere" contacts ||--o{ contact_tags : "etiquette" tags ||--o{ contact_tags : "attribue" ``` La table `roles` n'apparaît plus : supprimée par `007_no_roles.sql`. ## Tables | Table | Rôle | Exposée par l'API | |---|---|---| | `users` | Comptes utilisateurs (plus de `role_id`) | `/auth/*` | | `user_sessions` | Sessions persistées (`005`) | interne | | `password_reset_tokens` | Jetons de réinitialisation hachés | non (aucune route) | | `countries` | Référentiel ISO 3166 | `/countries` | | `organizations` | Entreprises | `/organizations` | | `contacts` | Interlocuteurs | `/contacts` | | `tags` / `contact_tags` | Étiquetage | non | | `pipeline_stages` | Étapes du pipeline | non | | `deals` | Affaires | non | | `deal_stage_history` | Historique des transitions | non | | `activities` | Appels, e-mails, réunions, notes | non | | `tasks` | Actions à mener | non | | `settings` | Configuration clé-valeur | non | | `audit_logs` | Piste d'audit | non | | `schema_migrations` | Versions appliquées | non | 16 tables après `007` (17 avant : la table `roles` ayant disparu). Seules celles marquées « `/…` » sont atteignables depuis le front. ## Conventions | Sujet | Choix | Raison | |---|---|---| | Noms de tables | pluriel `snake_case`, sans préfixe | les tables vivent dans une base dédiée, le préfixe serait redondant | | Noms de colonnes | `snake_case` | cohérent du DDL jusqu'au JSON | | Types d'horodatage | `DATETIME`, `DATETIME(3)` pour l'audit | évite la conversion de fuseau de `TIMESTAMP` et la limite de 2038 | | Durées de vie | `created_at`, `updated_at` sur toute table mutable | `ON UPDATE CURRENT_TIMESTAMP` garantit la fraîcheur sans code applicatif | | Suppression | `deleted_at`, jamais de `DELETE` métier | conserver l'historique et éviter les suppressions en cascade destructrices | | Identifiants | `CHAR(36)` pour les entités, `INT UNSIGNED` pour les référentiels | UUID stables hors base, entiers compacts pour les tables de référence | | Encodage | `utf8mb4` / `utf8mb4_unicode_ci` | accents et emoji, collation correcte | | Listes fermées | `CHECK` plutôt que table, sauf le pipeline | le jeu de valeurs est stable et court ; `pipeline_stages` reste une table car le nombre d'étapes varie selon les usages | Trois tables ne portent volontairement pas `updated_at` : `audit_logs`, `deal_stage_history` et `password_reset_tokens`. Elles sont en ajout seul. Une piste d'audit modifiable n'est plus une piste d'audit. Exception à la règle « jamais de `DELETE` » : **`countries` est supprimée en dur**. Référentiel fini, aucune entreprise ne peut pointer dessus (FK `SET NULL`), et un pays de trop poserait plus de problèmes qu'il n'en résout. ## Ce qui a été repris du CRM de référence | Décision | Origine | |---|---| | Le pipeline en table, pas en `ENUM` | la référence compte plus de vingt étapes réelles ; un `ENUM` aurait été ingérable | | Clé externe `UNIQUE` pour les imports | évite les doublons à l'ingestion et permet un `upsert` au `COALESCE` qui n'écrase jamais une saisie humaine | | `settings` en clé naturelle, sans surrogate | la clé est la donnée | | `snake_case` homogène DDL, TypeScript, JSON | seule chose réellement bien tenue de la référence | | Organisation en référentiel plutôt qu'en valeur figée | un rôle unique dans une colonne texte avait produit trois vocabulaires contradictoires | ## Ce qui a été corrigé | Défaut de la référence | Correction ici | |---|---| | Aucun `updated_at` | ajouté partout, maintenu par la base | | Suppressions dures, `ON DELETE CASCADE` sur l'audit | soft delete, et l'audit survit à la suppression d'un utilisateur (`ON DELETE SET NULL` + instantané `user_email`) | | `users.role` en texte libre | table `roles` + FK `RESTRICT` (`003`), **puis suppression totale des rôles par `007`** — choix assumé, voir ci-dessous | | Historique de statut limité à un niveau | `deal_stage_history` conserve toutes les transitions avec auteur et horodatage | | Aucun index de performance, filtrage et tri faits dans le navigateur | index composites `(deleted_at, …)` dimensionnés pour la pagination serveur | | `tokens.token` ni indexé ni haché | `token_hash CHAR(64)` indexé, le jeton en clair n'est jamais stocké | | Clé de déduplication d'envoi sans contrainte en base | contrainte composite en base plutôt qu'en application | | Aucune société, affaire, activité ni tâche | le modèle en tient compte dès le départ | | `int(11)` | `INT` ou `INT UNSIGNED` selon le cas | ## Migrations Les fichiers sont numérotés et appliqués dans l'ordre. Une migration déjà appliquée ne se modifie jamais : une correction passe par un nouveau fichier. | Fichier | Contenu | |---|---| | `000_schema_migrations.sql` | table de suivi des versions | | `001_initial_schema.sql` | 15 tables, 30 clés étrangères, 7 `CHECK` | | `002_reference_data.sql` | rôles, étapes, pays, réglages, étiquettes | | `003_integrity_backstop.sql` | clé étrangère `users.role_id` manquante, `CHECK` sur les champs obligatoires | | `004_audit_precision.sql` | millisecondes sur les colonnes d'audit | | `005_user_sessions.sql` | table `user_sessions` : sans elle, aucune session n'est possible | | `006_active_identity.sql` | colonnes générées `active_email` / `active_name` | | `007_no_roles.sql` | **suppression des rôles** : `DROP FOREIGN KEY fk_users_role`, `DROP COLUMN role_id`, `DROP TABLE roles` | Notes : - `003` existe parce que `001` avait été livrée avec la clé étrangère `users.role_id` absente alors que l'index était présent. Le cas a été trouvé en interrogeant la base, pas en relisant le SQL : c'est pourquoi chaque migration est validée par des inserts qui doivent échouer, pas seulement par une exécution sans erreur. - `005` a été nécessaire pour réutiliser `@cohaise/server` tel quel : le code partagé attend `user_sessions`, absente du modèle initial. - `006` corrige un oubli — `uq_contacts_email` et `uq_organizations_name` portaient sur la colonne brute, ce qui interdisait de réutiliser une adresse ou un nom après une suppression logique. Corrections en colonnes générées, à l'image du Cloud ; `001` n'a pas été retouché. - `007` annule `003` et vide `002` de son sens, sans les réécrire : c'est le principe même du fichier scellé. Le code, lui, a été vidé de `requireRole` et de `role_slug` en même temps. **Tout compte authentifié a tous les droits.** ## Sécurité (couche modèle) - Suppression d'un pays, d'un tag, d'une société référencée : `ON DELETE SET NULL` ou `RESTRICT`, la donnée métier survit. - Les identifiants d'organisation et de contact sont des UUID, non devinables dans les URL. - `audit_logs` est en ajout seul par convention applicative ; les colonnes portent la contrainte `JSON_VALID`. - Sessions : `user_sessions.token_hash` indexé, le jeton en clair n'est jamais stocké. Sessions, mots de passe, en-têtes et **absence de cloisonnement** : [`../../docs/security.md`](../../docs/security.md). ## Limites actuelles Seules les entités demandées sont exposées : `/auth/{login,logout,me,change-password}`, `/countries`, `/organizations`, `/contacts`. **Aucune route n'est protégée par un rôle** — le middleware `requireRole` n'existe plus dans le code. - **`owner_id` ne cloisonne rien** : la colonne est écrite et retournée dans les réponses, mais jamais filtrée. Toute ligne est visible et modifiable par tout compte authentifié. - Le premier compte se crée par `cohaise-crm-admin` (`make admin ARGS="--email … --first … --last …"`), jamais par une route publique. **Il n'existe pas d'option `--role`** : un compte créé a tous les droits. - `countries` ne compte que 19 entrées sur les ~250 de la norme ISO ; à compléter si l'usage le justifie. - Le pipeline (`deals`, `activities`, `tasks`, `tags`, `pipeline_stages`) existe en base mais **n'a ni route ni interface**. - Pas de journalisation des transitions en base : l'écriture dans `deal_stage_history` relève de l'application, à faire dans la même transaction que le changement d'étape. - `password_reset_tokens` est créée mais aucune route ne l'utilise. - Pas de rate limiting sur la connexion.