Files
CoHaiSe/docs/crm-api.md
T
Esiah 858d862fed
deploy / deploy (push) Canceled after 0s
feat: init repo
2026-11-10 19:56:03 +01:00

4.5 KiB

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

Base : /api/crm, plus GET /healthz (sonde base, 503 si indisponible). attachUser sur les quatre préfixes ; requireAuth sur chaque route sauf la connexion. 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/auth.ts:64
POST /api/crm/auth/logout routes/auth.ts:98
GET /api/crm/auth/me routes/auth.ts:105
POST /api/crm/auth/change-password routes/auth.ts:114
GET /api/crm/countries?q= routes/countries.ts:46
POST /api/crm/countries routes/countries.ts:57
PATCH /api/crm/countries/:id routes/countries.ts:88
DELETE /api/crm/countries/:id routes/countries.ts:132
GET /api/crm/organizations?q&page&limit routes/organizations.ts:105
GET /api/crm/organizations/:id routes/organizations.ts:135
POST /api/crm/organizations routes/organizations.ts:146
PATCH /api/crm/organizations/:id routes/organizations.ts:200
DELETE /api/crm/organizations/:id routes/organizations.ts:262
GET /api/crm/contacts?q&organizationId&page&limit routes/contacts.ts:96
GET /api/crm/contacts/:id routes/contacts.ts:140
POST /api/crm/contacts routes/contacts.ts:151
PATCH /api/crm/contacts/:id routes/contacts.ts:202
DELETE /api/crm/contacts/:id routes/contacts.ts:260

Conventions communes

  • Corps validés par Zod (createX/updateX, credentials, changePassword).
  • :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.