175 lines
9.3 KiB
Markdown
175 lines
9.3 KiB
Markdown
# 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.
|