Project Overview

Objectif

console-admin est une console d'administration pour gerer des entreprises, leurs etablissements, services, utilisateurs, roles, applications et environnements.

Le projet est en transition d'un modele ou le frontend parlait directement a Supabase vers un modele hybride:

• front conserve l'authentification utilisateur via Supabase
• back devient la couche d'API metier, de controle d'acces et d'orchestration
• Supabase reste la source de verite pour l'authentification et les donnees

Dossiers

• console/: application Nuxt 3
• auth/: portail SSO standalone Vue/Vite
• back/: API NestJS
• docs/: documentation projet, architecture et metier

Flux cible

1. l'utilisateur se connecte dans front via Supabase Auth
2. front recupere le access_token de session
3. front appelle back avec Authorization: Bearer <token>
4. back verifie le token, charge profiles et roles
5. back applique les regles metier et appelle Supabase si necessaire

Un second flux d'acces existe maintenant pour les integrations machine-to-machine:

1. un super-admin cree une API key dans la console
2. la cle est stockee cote backend sous forme de hash HMAC
3. le client technique appelle back avec x-api-key
4. back charge les metadonnees de la cle, verifie expiration/revocation et applique les scopes

Roles applicatifs observes

• super-admin
• administrateur
• utilisateur
• personnel

Seuls super-admin et administrateur ont actuellement acces a la console.

Regles de connexion console:

• un super-admin est redirige vers /
• un administrateur est redirige vers /etablissements
• un super-admin ou un administrateur peut se connecter soit par email + mot de passe + code TOTP, soit par magic link
• la double authentification TOTP s'active et se desactive depuis Mon Profil
• un utilisateur authentifie via Supabase est deconnecte puis refuse cote front
• un personnel authentifie via Supabase est deconnecte puis refuse cote front
• le message affiche reste non revelateur: Identifiant ou mot de passe incorrect.
• la deconnexion doit vider l'etat local et la session Supabase avant retour sur /login

Flux mot de passe + TOTP

flowchart TD
  A[Email + mot de passe] --> B[Supabase Auth]
  B --> C{Facteur TOTP actif ?}
  C -- Oui --> D[Saisie du code TOTP]
  D --> E[Session Supabase validee]
  C -- Non --> E
  E --> F[Chargement du profil]
  F --> G{Role console ?}
  G -- super-admin --> H[/]
  G -- administrateur --> I[/etablissements]
  G -- autre --> J[/login]

Flux magic link

flowchart TD
  A[Demande de magic link] --> B[Email envoye]
  B --> C[Clic sur le lien]
  C --> D[Session Supabase validee]
  D --> E[Chargement du profil]
  E --> F{Role console ?}
  F -- super-admin --> G[/]
  F -- administrateur --> H[/etablissements]
  F -- autre --> I[/login]

API keys

Le projet supporte maintenant des API keys pour des acces machine-to-machine.

Modele retenu:

• une cle est creee uniquement par un super-admin
• une cle porte un access_level
• super_admin donne un perimetre global
• enterprise_admin donne un perimetre limite a une entreprise
• les permissions techniques sont portees par des scopes

Type de cle	Perimetre	Entreprise requise	Exemple d'usage
super_admin	Global	Non	Synchronisation transverse
enterprise_admin	Une seule entreprise	Oui	Integration entreprise dediee

V1 actuellement en place:

• table public.api_keys
• table public.api_key_usage_logs
• expiration optionnelle
• revocation manuelle
• audit minimal d'usage
• historique detaille des usages consultable par super-admin
• scope backend expose: enterprises:read
• scopes backend exposes: enterprises:read, enterprises:write
• affichage du createur dans la console via createdByDisplayName

Affichage du createur:

• le backend expose createdByUserId et createdByDisplayName
• si le profil createur a disparu, un fallback email peut etre utilise
• si aucune information n'est recuperable, l'interface affiche Utilisateur supprime

Bonne pratique:

• conserver les cles API pour audit meme si leur createur est supprime
• eviter toute suppression en cascade depuis l'utilisateur vers api_keys
• idealement, persister plus tard un snapshot immuable du createur au moment de la creation

Flux simplifie:

Super-admin
  -> cree une API key dans la console
  -> transmet la cle au client technique
  -> le client appelle le backend avec x-api-key
  -> le backend controle scope + perimetre + statut de la cle
  -> l'usage est journalise

Un troisieme flux existe pour les applications Heriade externes:

1. l'application redirige vers la surface auth/ (auth.*) pour la connexion SSO
2. auth/ utilise une session Supabase existante ou demande une reconnexion
3. back valide le bearer Supabase et emet un app_access_token
4. l'application consomme ce token applicatif court
5. le switch de compte passe par accountId et le store multi-comptes du portail

Le portail utilisateur est expose separement sur portail.*. Si l'utilisateur arrive sur portail.* sans session locale, il est renvoye vers auth.*/login, puis revient sur le portail apres transfert de session.

API utilisateurs et profils

Le backend expose maintenant un domaine profiles pour centraliser la gestion des utilisateurs:

• creation d'un compte auth.users et de son profile
• lecture du profil courant ou d'un profil cible
• mise a jour des champs metier du profil
• changement d'email via endpoint dedie avec audit
• changement de mot de passe via endpoint dedie avec audit
• changement de role via endpoint dedie avec audit
• archivage / desarchivage via banned_until
• suppression definitive du compte et des profils associes

Perimetre	Lecture	Mise a jour	Creation	Archivage / suppression
super-admin	Toute entreprise, mais listing uniquement par entreprise	Oui	Oui	Oui
administrateur	Seulement son entreprise	Oui	Oui	Oui
utilisateur	Seulement lui-meme	Oui, champs profil seulement	Non	Non

Regles importantes:

• pas de reassignment d'entreprise via update
• pagination ajoutee sur GET /enterprises et GET /enterprises/:enterpriseId/profiles

Changement d'email:

• le changement d'email ne passe pas par PATCH /profiles/*
• il passe par POST /profiles/me/email ou POST /profiles/:id/email
• il est trace dans profile_email_change_audits
• le front utilisateurs passe maintenant par cette API backend pour la modification d'email

Impact utilisateur console:

• un super-admin peut changer l'email de tout utilisateur visible
• un administrateur peut changer l'email des utilisateurs de son entreprise
• un utilisateur peut changer son propre email via l'API dediee

Changement de mot de passe:

• le changement de mot de passe ne passe pas par PATCH /profiles/*
• il passe par POST /profiles/me/password ou POST /profiles/:id/password
• il est trace dans profile_password_change_audits
• aucun mot de passe en clair n'est journalise
• le front profil passe maintenant par cette API backend pour le changement de mot de passe courant
• le front utilisateurs passe maintenant par cette API backend pour le changement de mot de passe cible

Impact utilisateur console:

• un super-admin peut changer le mot de passe de tout utilisateur visible
• un administrateur peut changer le mot de passe des utilisateurs de son entreprise
• un administrateur ne peut pas changer le mot de passe d'un super-admin
• un utilisateur peut changer son propre mot de passe via son profil

Changement de role:

• le changement de role ne passe pas par PATCH /profiles/*
• il passe par POST /profiles/:id/role
• il est trace dans profile_role_change_audits
• un super-admin peut attribuer tous les roles, y compris super-admin
• un administrateur peut attribuer seulement administrateur, valideur, utilisateur
• ni administrateur ni super-admin ne peuvent changer leur propre role
• si un profil devient administrateur ou super-admin, ses rattachements etablissements/services sont purges automatiquement

Comptes personnels

Le backend expose maintenant un domaine personal-accounts pour les comptes gratuits de l'application:

• POST /personal-accounts permet une creation publique
• la creation publique utilise la validation email Supabase (auth.signUp)
• le role assigne est personnel
• une entreprise technique de type personal est creee pour ce compte
• un compte personnel peut modifier ou supprimer son propre compte
• un super-admin peut lister, modifier et supprimer tous les comptes personnels
• le DTO retourne emailConfirmed pour suivre l'etat de verification de l'email
• le DTO retourne aussi les settings de l'entreprise personal associee
• si l'email existe deja, l'API renvoie un conflit fonctionnel plutot qu'un message technique brut
• si Confirm email est desactive dans Supabase, les comptes personnels apparaissent immediatement comme confirmes

Impact front:

• la page console/pages/comptes-personnels.vue passe maintenant par le backend
• la liste des comptes personnels affiche Valide ou En attente selon emailConfirmed
• la creation avec un email deja pris affiche Cette adresse email est deja utilisee.
• les acces directs Supabase et edge functions historiques de ce flux ne sont plus utilises

Etat actuel de la migration

• l'authentification frontend est encore geree via Supabase client
• la route backend GET /enterprises existe et est consommee par le frontend pour la liste des entreprises
• le logo d'entreprise passe maintenant par les routes backend dediees POST /enterprises/:id/logo et DELETE /enterprises/:id/logo
• certaines operations entreprises restent encore en acces direct Supabase dans le frontend, notamment fetchById, create, update, remove