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

87 lines
4.5 KiB
Markdown

# 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 :
```json
{ "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.