Files
CoHaiSe/docs/crm-api.md
T
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

5.1 KiB

API et modèle de données — CoHaiSe CRM

Base : /api/crm, plus GET /healthz (sonde base, 503 si indisponible). attachUser sur auth, countries, organizations et contacts ; requireAuth sur toutes leurs routes sauf la connexion. POST /leads est public (formulaire de la vitrine). Aucune route n'est protégée par un rôle depuis 007_no_roles.sql.

Routes

Méthode Chemin Fichier
POST /api/crm/auth/login routes/authRoutes.ts
POST /api/crm/auth/logout routes/authRoutes.ts
GET /api/crm/auth/me routes/authRoutes.ts
POST /api/crm/auth/change-password routes/authRoutes.ts
GET /api/crm/countries?q= routes/countryRoutes.ts
POST /api/crm/countries routes/countryRoutes.ts
PATCH /api/crm/countries/:id routes/countryRoutes.ts
DELETE /api/crm/countries/:id routes/countryRoutes.ts
GET /api/crm/organizations?q&page&limit routes/organizationRoutes.ts
GET /api/crm/organizations/:id routes/organizationRoutes.ts
POST /api/crm/organizations routes/organizationRoutes.ts
PATCH /api/crm/organizations/:id routes/organizationRoutes.ts
DELETE /api/crm/organizations/:id routes/organizationRoutes.ts
GET /api/crm/contacts?q&organizationId&page&limit routes/contactRoutes.ts
GET /api/crm/contacts/:id routes/contactRoutes.ts
POST /api/crm/contacts routes/contactRoutes.ts
PATCH /api/crm/contacts/:id routes/contactRoutes.ts
DELETE /api/crm/contacts/:id routes/contactRoutes.ts
POST /api/crm/leads routes/leadRoutes.ts

Chaque route valide son corps puis délègue à services/*Service.ts ; aucune requête SQL n'est écrite dans routes/.

Conventions communes

  • Corps validés par Zod dans les routes (createXBody, updateXBody, credentials, newPassword, leadBody).
  • :id UUID validé par regex ⇒ 404 sinon (pays : entier > 0 sinon 404).
  • Pagination : limit borné 1..100, défaut 25 ; q fait une recherche texte.
  • Unicité violée (1062), FK référencée (1451/1452) ⇒ 409.
  • Suppression : DELETE FROM countries en dur ; organizations et contacts passent à deleted_at = NOW() et disparaissent des listes (WHERE deleted_at IS NULL).
  • Réponse d'erreur :
{ "error": { "status": 404, "code": "NOT_FOUND", "message": "…", "requestId": "…" } }

Modèle de données

backend/crm/migrations/ — 8 fichiers, application stricte dans l'ordre, checksum SHA-256 par fichier.

Fichier Contenu
000_schema_migrations.sql table de suivi (version, applied_at, checksum)
001_initial_schema.sql 15 tables : roles, users, password_reset_tokens, countries, tags, organizations, contacts, contact_tags, pipeline_stages, deals, deal_stage_history, activities, tasks, settings, audit_logs — 30 FK, 7 CHECK
002_reference_data.sql seeds : 3 rôles, 7 étapes de pipeline, 19 pays, 4 réglages, 5 tags
003_integrity_backstop.sql FK users.role_id (RESTRICT) + 6 CHECK de longueur
004_audit_precision.sql DATETIME(3) sur les journaux d'audit, l'historique de pipeline, deals, activités, tâches, last_login_at
005_user_sessions.sql table user_sessions (token_hash CHAR(64), FK CASCADE) ; purge confiée au service
006_active_identity.sql colonnes générées contacts.active_email, organizations.active_name (IF(deleted_at IS NULL, …, NULL) STORED) + index uniques dédiés
007_no_roles.sql suppression des rôles : DROP FOREIGN KEY fk_users_role, DROP COLUMN role_id, DROP TABLE roles

007 laisse 002 (seeds de rôles) et 003 (FK réintroduite) intacts : ces fichiers ne se re-modifient jamais, une migration appliquée est figée.

Entités exposées

Table Identifiant Remarques
users CHAR(36) UUID first_name, last_name, must_change_password, is_active, soft delete
organizations UUID FK countries (SET NULL), owner_id, created_by
contacts UUID FK organizations (SET NULL), pays, owner_id
countries INT UNSIGNED suppression physique
user_sessions — token_hash, expires_at, revoked_at

Hors API : deals, activities, tasks, tags, contact_tags, pipeline_stages, settings, password_reset_tokens, audit_logs.

Dérive de migrations

runMigrations() ne joue que les versions absentes et enregistre le SHA-256 du SQL ; assertNoDrift() refuse le démarrage si un fichier déjà appliqué a changé. CLI : cohaise-migrate --dir <dossier> [--dry-run] [--check], codes 0 / 1 (erreur ou dérive) / 2 (configuration).

Le DDL MariaDB n'est pas transactionnel : une migration interrompue se corrige par un nouveau fichier, jamais en éditant l'ancien.

make crm-migrate applique les migrations puis reconstruit et redémarre l'API : un binaire plus ancien que le schéma (par exemple du code qui lit encore roles après 007) répondrait NOT_MIGRATED alors que la base est à jour.