Files
CoHaiSe/backend/crm
Esiah 09cf07d79b feat: migrate showcase to Next.js and overhaul CRM UI
- rebuild the public site on the Next.js App Router with static export,
  per-section SEO pages, metadata, sitemap, robots and a generated OG image
- add full-screen scroll-snap regions, staged scroll reveals, a hash-free
  tab navigation with a sliding indicator and region-by-region menu scrolling
- replace the theme text toggle with animated sun/moon icons
- restructure the CRM API into config, middleware, models, routes, services
  and utils layers
- redesign the CRM shell with a single surface, tab rail, full-width blurred
  DataTable, record dialogs and mask-based icons
- update Docker/Nginx publishing, Makefile targets, shared UI polish and docs
2026-11-16 00:52:29 +01:00
..
2026-11-10 19:56:03 +01:00
2026-11-10 19:56:03 +01:00
2026-11-10 19:56:03 +01:00
2026-11-10 19:56:03 +01:00

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/deployment.md et ../../docs/security.md.

Modèle de données

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.

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.