47:Tb01, # Bases de données et stockage > 📍 **Où trouver ça dans l'UI** > - **Definitions** : Infra → onglet **Architecture** → **Databases** / **Storage** > - **Instances par env** : Infra → **Environments → {env} → Databases** / **Storage** Une app a souvent besoin de stocker des données. Wakastart supporte 2 grandes catégories. ## Base de données (Database) > **C'est quoi ?** Un système qui stocke des données structurées et permet de les requêter. C'est le coeur de la persistance de ton app. Moteurs disponibles dans Wakastart : | Engine | Type | Usage typique | |--------|------|---------------| | **PostgreSQL** | Relationnelle (SQL) | Le défaut pour la plupart des apps : transactions, schéma rigide | | **MongoDB** | Document (NoSQL) | Données flexibles, schemas évolutifs | | **Valkey** (= Redis) | Key-value en mémoire | Cache, sessions, file d'attente | ### 2 modes : `IN_CLUSTER` vs `MANAGED` | Mode | Où c'est hébergé | Pour | |------|------------------|------| | **IN_CLUSTER** | Dans le cluster K8s Wakastart, comme un pod | Dev, prototypes, faible volume | | **MANAGED** | Sur une infrastructure cloud managée (HA, backups auto, monitoring inclus) | Prod sérieuse | → Tu choisis le mode au niveau de la **Definition** (ex: `defaultMode: IN_CLUSTER` pour faciliter dev) et tu peux overrider par **Instance** (ex: en prod, on met `mode: MANAGED`). ### Pattern d'usage typique ``` DatabaseDefinition "primary" ├── engineType: POSTGRESQL ├── defaultMode: IN_CLUSTER ├── defaultPlan: "essential" └── defaultVersion: "15" ``` ## Stockage (Storage Bucket) — S3 > **C'est quoi un bucket S3 ?** Un système de stockage de **fichiers/objets** : images, vidéos, PDF, archives, exports CSV… Tout ce qui n'est pas structuré et n'a pas besoin d'un schéma relationnel. S3 = "Simple Storage Service" (à l'origine Amazon, repris par plusieurs providers avec une API compatible). Wakastart provisionne un bucket dédié pour chaque environnement. **Différence avec une BDD** : - BDD = données structurées, requêtables (SELECT, etc.). Performant pour lire des champs précis. - S3 = fichiers entiers, stockage froid pas cher. Tu PUT un fichier, tu GET un fichier. Pas de requête dedans. ### StorageBucketDefinition / StorageBucketInstance Même pattern que les databases : tu définis une fois au niveau Architecture, instancié par environnement. Une StorageBucketInstance produit pour le code applicatif **6 credentials** : - `S3_URL` — URL d'API S3 - `S3_ENDPOINT` — endpoint régional - `S3_REGION` — région physique - `S3_BUCKET` — nom du bucket - `S3_ACCESS_KEY_ID` — clé d'accès - `S3_SECRET_ACCESS_KEY` — clé secrète → Ton service les reçoit via des variables d'env (cf. chapitre Variables et secrets). 48:T16c2, # URLs et routing > 📍 **Où trouver ça dans l'UI** > - **Domaines et HttpRoutes de l'app** : Infra → onglet **Architecture** → **URLs** > - **URLs réelles par env** : Infra → **Environments → {env} → URLs** > **Comment tes utilisateurs accèdent à ton app ?** Wakastart gère le routing HTTP de bout en bout : DNS → load balancer → service. ## Domaines (App Domain) | Type | Exemple | Source | |------|---------|--------| | **PLATFORM_MANAGED** | `*.wakastart.app` | Géré par Wakastart, certificats SSL auto, gratuit | | **CUSTOM** | `exemple.com` | Tu apportes ton domaine, tu délègues la gestion du DNS chez Wakastart | ## App URL = sous-domaine + (préfixe d'env) + domaine Le pattern d'URL Wakastart insère le slug de l'environnement comme préfixe entre le sous-domaine et le domaine racine — sauf pour la prod, qui n'a pas de préfixe. ``` prod → sous-domaine "app" + domaine "exemple.com" = https://app.exemple.com dev → sous-domaine "app" + préfixe env "dev" + domaine = https://app.dev.exemple.com ``` ## Exposer une app à la racine d'un domaine (apex) Par défaut, une URL exige toujours un sous-domaine (`app`, `api`…). Mais si tu apportes un domaine **CUSTOM** (`monsupersite.com`), tu peux vouloir exposer ton app **directement à la racine** — sur `monsupersite.com`, sans aucun label devant. C'est ce qu'on appelle un **domaine apex**. > **Réservé aux domaines `CUSTOM`.** L'apex n'est pas disponible pour un domaine `PLATFORM_MANAGED` (`*.wakastart.app`), qui est partagé par toute la plateforme. Seul un domaine que tu apportes et dont tu délègues le DNS à Wakastart peut être exposé à sa racine. ### AppApexUrl (Architecture) → AppApexUrlInstance (par environnement) Comme le reste de l'architecture, l'apex se déclare **une fois** puis s'instancie **par environnement** : | Niveau | Ressource | Ce que tu décris | |--------|-----------|------------------| | **Architecture** | `AppApexUrl` | Le domaine `CUSTOM` à exposer + le service ciblé + le chemin. **Pas de sous-domaine** (c'est justement le principe). | | **Environnement** | `AppApexUrlInstance` | La matérialisation de cet apex dans un environnement donné — c'est **là que le provisioning réel** (DNS, certificat, routing) a lieu. | Un domaine ne peut porter qu'**un seul apex** (contrainte d'unicité en base). Une app peut en revanche avoir plusieurs domaines `CUSTOM`, chacun avec son propre apex. ### DNS : toujours un enregistrement `A`/`AAAA`, jamais un `CNAME` Un `CNAME` à la racine d'une zone est structurellement invalide (RFC 1034/1912). Pour tout hostname apex, Wakastart force donc automatiquement un enregistrement `A`/`AAAA`, quel que soit le provider — tu n'as rien à configurer côté DNS, c'est géré à l'instanciation. ### Avertissement obligatoire à l'instanciation Exposer un domaine à sa racine écrit un enregistrement DNS à la racine **sans sous-domaine**. Or Wakastart **ne vérifie pas** ce qui résout déjà sur ce domaine : un site tiers déjà en production dessus (hébergé ailleurs, ou un enregistrement DNS manuel existant) peut être rendu inaccessible ou entrer en conflit. Pour cette raison, la console affiche une **modale de confirmation bloquante** avant toute création d'un apex — tu dois confirmer explicitement que tu veux exposer le domaine racine. La vérification de l'usage actuel du domaine reste à ta charge. ## HttpRoute = routing interne d'une URL À une URL on attache une **HttpRoute** qui dit "envoie tout `/api/*` vers le ServiceInstance backend, tout `/` vers le ServiceInstance frontend". C'est du routage applicatif (équivalent d'un reverse proxy nginx, mais déclaratif). ``` https://app.dev.exemple.com/api/users ↓ Gateway Wakastart ↓ Match HttpRoute path /api/* ↓ Forward vers ServiceInstance "backend" ↓ Pod backend renvoie 200 OK ``` ## URL front officielle (Primary Front URL) Une app peut avoir plusieurs routes (`AppRoute`) pointant vers plusieurs services de rôle `FRONT` (front web, front mobile packagé en PWA, etc.). Rien ne distingue par défaut laquelle est "la" URL front de référence de l'app. Sur l'écran Architecture → URLs, chaque route ciblant un service `role: FRONT` peut être désignée comme **URL front officielle** de l'app : - Via l'étoile dans le tableau des routes, ou via la case à cocher du dialogue de création/modification de route. - Une seule route active peut porter ce flag par app (contrainte imposée en base par un index partiel unique) — cocher une nouvelle route désactive automatiquement l'ancienne (comportement radio-button, pas de confirmation nécessaire). - Le flag n'est disponible que pour une route dont le service cible a `role: FRONT` — pour tout autre rôle (`BACK`, `BFF`, `WORKER`), l'action est indisponible. > **Important** : ce flag est purement déclaratif/affichage. Il ne pilote aucune ressource K8s/cloud et n'a aucune influence sur les variables `ROUTE_*` injectées aux services — il sert uniquement à savoir "quelle URL montrer à un humain" pour cette app. ### Consulter l'URL par environnement L'endpoint `GET /app-routes/primary-front-url-by-environment?appId=` résout la route désignée et calcule son FQDN pour chaque environnement de l'app : | Statut | Signification | |--------|----------------| | `READY` | Route provisionnée dans cet environnement — l'URL est utilisable | | `PENDING` | Route déclarée dans l'architecture mais pas encore synchronisée/provisionnée dans cet environnement | | `NOT_CONFIGURED` | Aucune route n'est désignée comme officielle pour cette app | Côté dashboard, cette information est affichée via le bouton **Voir les URLs** sur la liste des Applications. 49:T11c6, # Variables et secrets > 📍 **Où trouver ça dans l'UI** > - **Variables attendues par un service** : Infra → onglet **Architecture** → **Services** → la ServiceDefinition concernée > - **Configuration d'un environnement** : Infra → **Environments → {env} → Configuration** > - **Binding service ↔ configuration** : Infra → **Environments → {env} → Services** → la ServiceInstance La config consommée par un service (URL de la BDD, JWT secret, clé API externe, niveau de log…) circule à travers trois niveaux dans Wakastart : **déclaration côté architecture**, **configuration côté environnement**, puis **binding** dans chaque ServiceInstance. ## 1. Architecture : déclarer ce que le service attend Quand tu crées une ServiceDefinition, tu listes les variables que ton service consomme : ``` ServiceDefinition "backend" ├── requires JWT_SECRET ├── requires DATABASE_URL ├── requires S3_BUCKET └── requires LOG_LEVEL ``` **Seules les variables déclarées ici peuvent être bindées dans les environnements.** Si ton service a besoin d'une nouvelle config, il faut d'abord la déclarer dans l'architecture. ## 2. Configuration d'un environnement La **Configuration** d'un environnement est l'**inventaire des valeurs disponibles** dans cet env, à partir desquelles tes services peuvent se servir. Elle est **commune à tous les services de l'environnement**. ### D'où viennent les entrées de Configuration | Source | Exemple | Géré par | |--------|---------|----------| | **Plateforme** | URL interne d'un service Wakastart (Discovery, IAM…) | Wakastart (auto-généré, dynamique) | | **Environnement** | URL d'une DatabaseInstance, credentials S3, URL publique d'un autre service de l'app | Wakastart (dérivé des ressources de l'env) | | **Utilisateur** | API key d'un service externe, JWT secret, `LOG_LEVEL`… | Toi, via l'UI | ### Secret vs non-secret Chaque entrée de configuration peut être marquée **secret** ou non : | | Lecture après création | Visible dans l'UI | Usage typique | |--|----------------------|-------------------|---------------| | **Non-secret** | Oui, modifiable | Valeur en clair | `LOG_LEVEL`, `NODE_ENV`, hostnames publics | | **Secret** | Non — uniquement par les services au runtime | Valeur masquée | `JWT_SECRET`, mot de passe BDD, API key externe | Un secret est stocké chiffré dans le coffre-fort Wakastart. Une fois créé, **sa valeur n'est plus consultable dans l'UI** — seuls les pods de tes services peuvent la lire au démarrage. ## 3. Binding : connecter un service à la Configuration Pour chaque ServiceInstance, tu fais un **binding** entre une variable attendue par le service (déclarée dans sa ServiceDefinition) et une entrée de la Configuration de l'env. ``` ServiceInstance "backend" en env prod ├── JWT_SECRET ──bind──> entrée Configuration "jwt-secret" (secret utilisateur) ├── DATABASE_URL ──bind──> entrée Configuration "primary-db-url" (auto, DatabaseInstance) ├── S3_BUCKET ──bind──> entrée Configuration "medias-bucket" (auto, StorageBucketInstance) └── LOG_LEVEL ──bind──> entrée Configuration "log-level" (utilisateur) ``` Au démarrage du pod, chaque env var reçoit la valeur de l'entrée bindée. ## Mutualiser : une valeur, plusieurs services Si plusieurs services ont besoin de la **même** valeur (ex: `STRIPE_API_KEY` utilisée par `backend` et `worker`), **ne crée pas deux entrées identiques**. Crée **une seule entrée** dans la Configuration de l'env et bind-la dans chaque ServiceInstance qui en a besoin. Avantages : - **Une seule source de vérité** — pas de drift entre services - **Mise à jour atomique** — changer la valeur = changer un seul endroit, tous les services concernés la récupèrent au prochain redémarrage - **Pas de duplication dans les secrets** — un secret est stocké une fois, pas N fois ## Les variables plateforme sont dynamiques Les entrées générées par la plateforme ou par l'environnement (URL de la BDD, URL d'un service interne, hostname public d'un autre service de l'app, credentials S3…) sont **dynamiques** : si la ressource sous-jacente change (la BDD est migrée vers un nouveau hostname, un service est renommé, un secret S3 est rotaté…), la valeur de l'entrée suit automatiquement. → Tu **ne casses jamais un binding** en faisant évoluer ton infrastructure. Les services redémarrés récupèrent les nouvelles valeurs. 4a:T2508, # Redirections d'URL > 📍 **Où trouver ça dans l'UI** > - **Niveau Network** : Organisation → **Réseaux** → configuration d'un réseau → **Redirections d'URL** > - **Niveau Customer** : Organisation → **Clients** → configuration d'un client → **Redirections d'URL** Une redirection d'URL est une ressource qui répond HTTP 302 sur une URL "source" vers une URL "destination" pointant vers une route existante d'une app, dans un environnement donné. Elle peut être déclarée à trois niveaux (`scopeType`), exclusifs entre eux : | Scope | Qui la déclare | Cas d'usage typique | |-------|----------------|---------------------| | `NETWORK` | Un réseau (tenant en aval de l'app) | Redirection au niveau d'un réseau | | `CUSTOMER` | Un client (tenant en aval de l'app) | Redirection au niveau d'un client | | `APP` | L'équipe de l'app elle-même | `www.monsupersite.com` ↔ `monsupersite.com` | Les scopes `NETWORK` et `CUSTOMER` — décrits dans le reste de cette page — désignent les **tenants en aval de l'app** et restent inchangés. Le scope `APP`, décrit [plus bas](#redirections-a-lechelle-de-lapp-app-scope), concerne l'app elle-même ; c'est un modèle dédié, pas une variante des deux autres. Contrairement au routing applicatif standard (voir [URLs et routing](./routing-urls)), une redirection ne route pas de trafic applicatif : elle se contente de rediriger le navigateur vers l'URL finale. ## Bloc Source — immuable après création | Champ | Description | |-------|--------------| | **Domaine** | Un domaine `CUSTOM` appartenant à l'app, ou un domaine `PLATFORM_MANAGED` commun à toute la plateforme (ex. `y.wakastart.app` sur dev) | | **Sous-domaine** | Un label unique, validé comme les sous-domaines de service (caractères DNS valides, un seul label — pas de points) | L'URL source réelle n'est **pas saisie** : elle est calculée automatiquement à partir du sous-domaine, du domaine, et — si le domaine est `PLATFORM_MANAGED` — du shortname de l'app : ``` ... ``` > **Important** : le préfixe d'environnement inséré dans l'URL source vient de l'**environnement CIBLE** choisi dans le bloc Destination — il n'existe pas d'environnement propre à la source. Conséquence directe : changer l'environnement cible d'une redirection **change son URL source** (le DNS est migré automatiquement), sans jamais toucher à l'URL ni à l'infra de la destination elle-même. **Exemple concret** : ``` Sous-domaine : monclient Domaine : y.wakastart.app (PLATFORM_MANAGED) App shortname : 7owwaa Env cible (préfixe): dev → URL source : monclient.dev.7owwaa.y.wakastart.app ``` Deux redirections peuvent partager le même sous-domaine + domaine tant que leurs environnements cibles ont des préfixes différents — il n'y a alors aucune collision DNS réelle (le préfixe d'env fait partie du FQDN final). ## Bloc Destination — éditable à tout moment | Champ | Description | |-------|--------------| | **Route (AppRoute)** | Route existante de l'app à cibler | | **Environnement** | Environnement dans lequel la route est provisionnée | | **Path** | Chemin ajouté à l'URL de destination (optionnel) | | **Query string** | Paramètres de requête ajoutés à l'URL de destination (optionnel) | Le domaine/host de la destination **n'est jamais saisi manuellement** : il découle exclusivement de la route + de l'environnement sélectionnés, recalculé automatiquement à chaque changement. > **Important** : modifier la destination (route, environnement, path ou query) ne déploie et ne modifie **jamais** l'infra réelle de cette destination. L'AppUrl / la route cible reste gérée exclusivement par l'architecture applicative de l'app — la redirection ne fait que mettre à jour sa propre configuration HAProxy interne. ## Statuts Cycle de vie standard des ressources Wakastart : | Statut | Signification | |--------|----------------| | `PENDING` | Redirection créée en DB, en attente de traitement par l'operator | | `PROVISIONING` | Ressources K8s en cours de création | | `PROVISIONED` | Redirection active — l'URL source répond bien en 302 vers la destination | | `FAILED` | Échec du provisioning | | `DESTROYING` | Suppression en cours | | `DESTROYED` | Redirection supprimée | Un **drift** est détecté si l'URL réelle de la route cible a changé depuis la dernière réconciliation (par exemple si l'app a modifié son architecture entre-temps) — la redirection reste fonctionnelle mais nécessite une resynchronisation. ## Mécanisme technique Le routing applicatif classique de Wakastart passe par Gateway API + Istio, via une `HttpRoute` avec un filtre `RequestRedirectFilter` pour les redirections simples. Ce mécanisme **ne suffit pas** ici : Gateway API ne supporte pas la réécriture de query string dans une redirection, or les redirections Wakastart doivent pouvoir ajouter/modifier des paramètres de requête. Un composant **HAProxy dédié et mutualisé pour toute la plateforme** (namespace `wakastart-redirects`) prend donc en charge la réécriture effective : ``` https://monclient.dev.7owwaa.y.wakastart.app │ ▼ DnsRecord + ListenerSet + HttpRoute (standard, côté API infra) │ ▼ HttpRoute route vers le Service HAProxy partagé (au lieu du Service applicatif classique) │ ▼ HAProxy lit sa map (host → URL cible) et répond 302 │ ▼ https:///? ``` Chaque redirection crée donc, côté `ws-serv-infra`, les mêmes ressources standard qu'une route applicative (`DnsRecord`, `ListenerSet`, `HttpRoute`) — seule différence : la `HttpRoute` pointe vers le service HAProxy partagé plutôt que vers un `ServiceInstance` applicatif. La configuration effective (mapping host → URL cible) est un fichier `map_str` généré par l'operator et poussé dans une `ConfigMap`. Chaque changement (création, modification de destination, suppression) déclenche un **rollout automatique** du déploiement HAProxy pour recharger la map à jour. ## Redirections à l'échelle de l'app (App-scope) Les scopes `NETWORK` et `CUSTOMER` ci-dessus s'adressent aux tenants en aval de l'app. Le scope **`APP`** répond à un autre besoin : permettre à **l'équipe de l'app elle-même** de rediriger une URL vers une autre au sein de sa propre app — typiquement basculer entre `www.monsupersite.com` et `monsupersite.com`. > **Un modèle dédié, pas une extension des scopes existants.** Le scope `APP` s'appuie sur des ressources qui lui sont propres (`AppUrlRedirect` / `AppUrlRedirectInstance`). Les redirections `NETWORK`/`CUSTOMER` ne sont pas modifiées et restent gérées comme décrit plus haut. > **Réservé aux domaines `CUSTOM`.** Comme pour l'apex (voir [URLs et routing](./routing-urls)), une redirection App-scope n'est possible que sur un domaine `CUSTOM` rattaché à l'app — jamais sur un domaine `PLATFORM_MANAGED` partagé. ### AppUrlRedirect (Architecture) → AppUrlRedirectInstance (par environnement) Comme le reste de l'architecture, une redirection App-scope se déclare **une fois**, sans jamais choisir d'environnement, puis s'instancie **par environnement** : | Niveau | Ressource | Ce que tu décris | |--------|-----------|------------------| | **Architecture** | `AppUrlRedirect` | La source (domaine `CUSTOM` + sous-domaine source, ou **l'apex** si aucun sous-domaine) et la cible : soit une URL existante de l'app, soit son apex. | | **Environnement** | `AppUrlRedirectInstance` | La matérialisation de cette redirection dans un environnement donné — c'est là que le provisioning réel a lieu. | La cible reste toujours **au sein de la même app** : une URL déjà déclarée dans l'architecture, ou l'apex de l'app. Il n'y a donc pas de redirection ouverte possible — la destination est résolue côté serveur. ### Même mécanisme technique Une redirection App-scope réutilise exactement le composant **HAProxy mutualisé** (`wakastart-redirects`) décrit ci-dessus : mêmes ressources standard côté API infra (`DnsRecord`, `ListenerSet`, `HttpRoute` pointant vers le service HAProxy partagé), même map `host → URL cible` rechargée à chaque changement. Rien de spécifique à provisionner. > **Avertissement à la source apex.** Si la source d'une redirection App-scope est l'apex (aucun sous-domaine), la même modale de confirmation bloquante que pour l'exposition à la racine (voir [URLs et routing](./routing-urls)) s'applique : la plateforme ne vérifie pas ce qui résout déjà sur ce domaine. Un domaine ne peut d'ailleurs pas porter à la fois un apex et une redirection App-scope apex-source. ## Limites connues - **RBAC** : pas de contrôle d'accès fin au-delà de `WakaAdmin` / `OwnerAdmin` (accès complet aux redirections), en plus du cloisonnement Network/Customer standard. - **Plafond** : 20 redirections maximum par scope. Il s'agit d'une limite de sécurité technique actuelle, sans justification fonctionnelle — elle peut évoluer. - **Suppression** : contrairement aux autres ressources infra qui bloquent leur suppression tant que des enfants existent, supprimer une redirection ne bloque **jamais** sur l'état de sa destination — la route/l'environnement ciblé n'est pas affecté. 4b:T627, # Environnements > 📍 **Où trouver ça dans l'UI** — Infra → onglet **Environments** (liste) ; clique un env pour son dashboard complet > **Un environnement = une instance complète et isolée de ton app**. ## Champs principaux d'un environnement | Champ | Exemple | Rôle | |-------|---------|------| | `env` | `dev` / `prod` / `staging` | Type d'environnement | | `shortname` | `exemple` | Surnom court de l'app dans cet env | | `slug` | `exemple-dev` | Identifiant unique de l'environnement (utilisé dans les URLs) | | `gitRef` | `main` / `dev` / `feature/X` | Branche Git surveillée par cet env | | `gitRefType` | `BRANCH` / `TAG` / `COMMIT` | Type de référence Git | | `autoDeployEnabled` | `true` / `false` | Auto-deploy quand un build sur cette ref réussit | ## Cycle de vie d'un env ``` ACTIVE → (pause) → PAUSED → (resume) → ACTIVE ↓ DELETING → (cleanup) → supprimé ``` ## Le tableau de bord d'un environnement Quand tu cliques sur un environnement, tu accèdes à : | Onglet | Contenu | |--------|---------| | **Résumé** | Vue d'ensemble (services up, dernière deploy, health) | | **Services** | Liste des ServiceInstances avec leur état runtime | | **Deployments** | Historique des versions déployées + rollback | | **Configuration** | Variables et secrets de l'env | | **Jobs** | Tâches scheduled (cron jobs) | | **Databases** | Les DatabaseInstances de cet env | | **Storage** | Les StorageBucketInstances de cet env | | **URLs** | Les URLs publiques de cet env | | **Monitoring** | Métriques, logs centralisés | 4c:T4fe, # Builds et Deployments — différence > 📍 **Où trouver ça dans l'UI** > - **Builds** : Infra → onglet **Builds** > - **Deployments** : Infra → **Environments → {env} → Deployments** C'est une distinction qui peut piéger : | | Build | Deployment | |--|-------|------------| | **Quoi** | Convertit du code en image Docker | Lance une image existante dans un environnement | | **Niveau** | App (architecture) | Environnement | | **Concerne** | Une ServiceDefinition | Une ServiceInstance | | **Result** | Une image disponible dans le registry | Des pods qui tournent dans un environnement | ## Workflow typique 1. Tu commits du code et tu push sur `main` 2. Wakastart **build** : `main` HEAD → image `:abc123` 3. Une fois `SUCCEEDED`, en mode AUTO, l'image est **deployed** dans les environnements qui surveillent `main` 4. Wakastart applique → les pods sont mis à jour (rolling update sans coupure) 5. Le **Deployment** apparaît dans l'onglet Deployments de l'env, avec statut `IN_PROGRESS` puis `SUCCEEDED` ## Modes de déploiement (DeploymentMode) | Mode | Comportement | |------|--------------| | `AUTO` | Auto-deploy dès qu'un build sur la branche surveillée réussit | | `MANUAL` | Tu choisis explicitement quand déployer (et quelle image) | 4d:Tc2f, # Workflow complet — créer une app de zéro Voici une narration de bout en bout pour bien comprendre comment tout s'enchaîne. ## Étape 1 — Créer l'App Tu vas dans l'UI, "Nouvelle App", tu donnes un nom. Wakastart crée : - L'enregistrement `App` en DB - Un espace dédié dans le registry pour tes futures images Docker - Un espace dédié dans le coffre-fort de secrets pour tes credentials ## Étape 2 — Définir l'Architecture Tu navigues dans **Infra → Architecture**. Tu crées : 1. **Un Repository** managé `exemple-backend` (Wakastart crée le repo sur GitHub via l'org `Waka-Start`) 2. **Une ServiceDefinition** `backend` (role: BACK, exposure: PUBLIC, port: 3000, depuis le repo `exemple-backend`) 3. **Une DatabaseDefinition** `primary` (engine: PostgreSQL, defaultMode: IN_CLUSTER) 4. **Une StorageBucketDefinition** `medias` (defaultMode: MANAGED) ## Étape 3 — Créer un environnement Tu crées un environnement `dev` : - gitRef: `main` - autoDeploy: true → Wakastart crée pour cet environnement : - Un namespace Kubernetes dédié qui isole les ressources de l'env - Les DatabaseInstance et StorageBucketInstance correspondant aux Definitions (in-cluster en dev) - Les credentials applicatives pour accéder aux ressources de l'env - Une URL platform-managed `app.dev.exemple.wakastart.app` ## Étape 4 — Build et déployer Tu commits du code, tu push sur `main`. Wakastart : 1. Détecte le push via webhook GitHub 2. Crée un **Build** PENDING 3. Le build passe BUILDING → PUSHING → SUCCEEDED 4. Mode AUTO → l'image est **déployée** dans l'env `dev` 5. Un **Deployment** apparaît, status PROGRESSING, puis SUCCEEDED 6. Tes pods tournent, ton API est accessible sur `app.dev.exemple.wakastart.app` ## Étape 5 — Promouvoir en prod Tu crées un environnement `prod` : - gitRef: `prod` (branche dédiée) - autoDeploy: true - Tu overrides ta DatabaseInstance : `mode: MANAGED` (PostgreSQL managé, HA + backups auto) - Tu ajoutes un domaine custom `exemple.com` → Ton app tourne en prod sur infrastructure managée, isolée du dev. --- ## Questions fréquentes **"Pourquoi y a-t-il une distinction Definition / Instance ?"** → Pour que tu puisses définir ton architecture **une seule fois** et la dupliquer dans plusieurs environnements avec des overrides locaux (plan moins cher en dev, plus puissant en prod). **"Mon build a échoué, où je regarde ?"** → **Infra → Builds → cliquer sur le build** : tu vois les logs Docker build et l'erreur précise. **"Mon service ne démarre pas, où je regarde ?"** → **Infra → Environments → {env} → Services → {service}** : onglet **Logs** pour les logs du conteneur, onglet **Deployments** pour voir si le déploiement a échoué. **"Comment je rotate les credentials de ma BDD ?"** → Pour les bases en mode `MANAGED` : la rotation est déclenchée côté provider cloud. Les secrets K8s sont régénérés et les services redéployés. **"Comment je restore une sauvegarde ?"** → **Infra → Backups** : tu vois la liste des sauvegardes, tu cliques **Restore** sur celle voulue. 4e:T3a22, # Bonnes pratiques de déploiement Ces règles sont issues des incidents rencontrés sur des services réels. Elles couvrent tout ce qui peut casser silencieusement un déploiement : config manquante, image Docker mal construite, migrations DB oubliées, runtime config Next.js mal alignée, intégration OAuth/Keycloak bancale. --- ## 1. Variables d'environnement Chaque fichier `.env.example` constitue un **contrat de configuration**. Il doit être exhaustif, auto-documenté et maintenu à jour à chaque évolution du projet. ### 1.1 Règles obligatoires pour chaque variable | Icône | Attribut | Exigence | |---|---|---| | 📝 | Exemple de valeur | Fournir une valeur d'exemple réelle et fonctionnelle. Pas de placeholder vide type `xxx` ou `changeme`. | | 📌 | Description contextuelle | Expliquer en une phrase pourquoi cette variable est nécessaire au fonctionnement de l'application. | | 🔁 | Doublon inter-services | Si la même valeur est attendue dans un autre microservice (ex: front ET back), documenter le doublon, expliquer pourquoi il existe, et préciser que toute modification doit être répercutée sur tous les services concernés. | | ✅ / ⚠️ | Obligatoire ou optionnelle | Indiquer clairement si la variable est requise ou optionnelle, et décrire l'impact de son omission (comportement dégradé, erreur fatale, fonctionnalité désactivée…). | | 🌐 | Type URL | Si la valeur est une URL, préciser si elle doit être publique (accessible depuis le navigateur) ou privée (accessible uniquement depuis le réseau interne / pod K8s). | | 🧪 | Dev uniquement | Si la variable n'est utilisée qu'en dev, l'indiquer explicitement et expliquer pourquoi elle n'est pas nécessaire en prod. | | 🔐 | Secret | Si la lecture de cette valeur par une personne non autorisée constitue un risque (fuite de données, accès dangereux — ex: `DATABASE_URL`, clés API, tokens), la marquer comme SECRET. | | 🔑 | Impact chiffrement / autorisation | Si la variable impacte un chiffrement ou un système d'autorisation, documenter : (1) les services devant partager la même valeur, (2) les risques de modification (ex: perte définitive d'accès aux données chiffrées), (3) le format attendu et la commande de génération. | ### 1.2 Exemple de documentation ```env # URL de l'API backend consommée par le frontend. # TYPE: URL publique (accessible depuis le navigateur de l'utilisateur). # OBLIGATOIRE — sans cette variable, toutes les requêtes API échouent. # DOUBLON: Cette variable correspond à BACKEND_URL côté backend. # La modifier ici implique de mettre à jour BACKEND_URL dans le service backend. NEXT_PUBLIC_API_URL=https://api.exemple.com # Clé de chiffrement des tokens de session. # TYPE: SECRET — ne jamais committer en clair ni modifier sans plan de migration. # ATTENTION: Modifier cette valeur invalide tous les tokens actifs. # FORMAT: 32 bytes hex — générer avec: openssl rand -hex 32 ENCRYPTION_KEY= ``` ### 1.3 `NEXT_PUBLIC_*` vs variables runtime (Next.js) Les variables `NEXT_PUBLIC_*` sont **compilées au moment du build** par Next.js et inlinées dans le bundle JS. Elles ne peuvent pas être modifiées à l'exécution du conteneur. Si une URL doit pouvoir être configurée sans rebuild (ex: URL de Keycloak, URL d'API), elle doit passer par le mécanisme `window.__RUNTIME_CONFIG__` injecté par `docker-entrypoint.sh` (voir [section 4](#4-runtime-config-du-frontend-nextjs)). Documenter explicitement dans le `.env.example` de chaque service : - quelles variables sont compilées au build (`NEXT_PUBLIC_*`) - lesquelles sont injectées à l'exécution via `window.__RUNTIME_CONFIG__` - en cas de doublon entre les deux mécanismes, laquelle a la priorité et pourquoi > ⚠️ Ne jamais committer un fichier `.env` réel dans le dépôt Git. Seul le `.env.example` (sans valeurs secrètes réelles) est versionné. --- ## 2. Dockerfile et migrations Prisma En l'absence d'outillage CI/CD avancé, toute application nécessitant une base de données doit garantir l'application automatique des migrations Prisma au démarrage du conteneur. ### 2.1 Entrypoint obligatoire pour les applications avec Prisma Le Dockerfile de toute application backend utilisant Prisma doit déléguer le démarrage à un script `entrypoint.sh`. Ce script applique les migrations avant de démarrer le processus Node.js principal. **Structure type d'un `entrypoint.sh`** : ```sh #!/bin/sh set -e echo '[entrypoint] Running Prisma migrations...' npx prisma migrate deploy echo '[entrypoint] Starting application...' exec node dist/main.js ``` **Configuration Dockerfile associée** : ```dockerfile FROM node:20-alpine WORKDIR /app COPY . . RUN npm install --omit=dev RUN npx prisma generate RUN npm run build COPY entrypoint.sh /entrypoint.sh RUN chmod +x /entrypoint.sh ENTRYPOINT ["/entrypoint.sh"] ``` ### 2.2 Pièges à éviter - ✅ `prisma` doit figurer dans les `dependencies` (et **non** `devDependencies`) pour être disponible lors de l'exécution du conteneur de production. - 🚨 Ne **jamais** utiliser `pnpm prune --prod` sans avoir vérifié que `prisma`, `prisma generate` et tous les binaires natifs nécessaires (`bcrypt`, `multer`…) sont dans les `dependencies` de production. ### 2.3 Seed optionnel : injecter des données initiales ou de test Le conteneur de votre service est le seul point d'entrée vers sa base de données en ligne. Pour **réinjecter des données** (jeu de référence, données de démo, ou les données de test de votre environnement local) dans un déploiement Wakastart, le bon endroit est le **même `entrypoint.sh`**, **après** l'application des migrations et **avant** le démarrage de l'application. Le seed doit pouvoir être **piloté par une variable d'environnement** : un conteneur redémarre régulièrement (rollout, scale, crash), donc on ne veut pas le relancer à chaque démarrage. La variable permet de l'activer ponctuellement sur l'environnement voulu (typiquement en dev), puis de le désactiver une fois les données injectées. **Étape 1 — Déclarer la commande de seed dans `package.json`** : ```json { "prisma": { "seed": "ts-node prisma/seed.ts" } } ``` > `npx prisma db seed` exécute la commande définie dans le bloc `prisma.seed`. Vous pouvez aussi utiliser votre propre script (`npm run seed`). **Étape 2 — Conditionner le seed dans `entrypoint.sh`** : ```sh #!/bin/sh set -e echo '[entrypoint] Running Prisma migrations...' npx prisma migrate deploy # Seed optionnel — uniquement si RUN_SEED=true if [ "$RUN_SEED" = "true" ]; then echo '[entrypoint] RUN_SEED=true → seeding database...' npx prisma db seed else echo '[entrypoint] RUN_SEED non activé → seed ignoré.' fi echo '[entrypoint] Starting application...' exec node dist/main.js ``` **Étape 3 — Piloter `RUN_SEED` via les variables Wakastart** : la variable se définit comme n'importe quelle config var de votre service (voir [Variables & secrets](/v1.0/dev/29-vars-secrets)). Mettez `RUN_SEED=true` sur l'environnement où vous voulez injecter les données (ex. un env de dev), déployez, puis **repassez la variable à `false`** une fois le seed appliqué pour éviter qu'il ne se rejoue au prochain redémarrage. **Bonnes pratiques** : - ✅ Le script de seed doit être **idempotent** : utilisez des `upsert` (ou un garde « ne rien faire si la table est déjà peuplée ») plutôt que des `create`, pour pouvoir le rejouer sans créer de doublons. - ✅ `ts-node` (ou l'outil utilisé par votre commande de seed) doit être disponible à l'exécution dans l'image — placez-le dans les `dependencies` si vous l'appelez au runtime, ou compilez le script de seed avec le reste de l'application. --- ## 3. TypeScript et build NestJS / Node.js Les erreurs de build TypeScript sont une cause fréquente de déploiements silencieusement cassés. | Règle | Détail | |---|---| | **`rootDir` obligatoire** dans `tsconfig.build.json` | Toujours déclarer `rootDir: "./src"` pour garantir que la sortie compilée est dans `dist/main.js` et non `dist/src/main.js`. Sans `rootDir`, le chemin de sortie dépend du module résolu et casse le démarrage du conteneur. | | **Éviter les imports hors `rootDir`** | Ne jamais importer depuis `../package.json` ou tout chemin situé hors du `rootDir` défini. Ces imports provoquent des erreurs `tsc` et ne sont pas accessibles dans l'image Docker de production. | | **Scripts `postinstall` avec pnpm v10+** | pnpm v10 bloque les scripts `postinstall` par défaut. Configurer explicitement `pnpm.onlyBuiltDependencies` dans `package.json` pour autoriser la génération des binaires Prisma, bcrypt et autres dépendances natives. | | **Dépendances natives en production** | `multer`, `bcrypt` et tous les packages requis à l'exécution doivent être dans `dependencies` et non `devDependencies`, même s'ils sont utilisés via un framework comme NestJS. | | **`prisma.config.ts` sans `dotenv`** | Ne pas importer `dotenv/config` dans `prisma.config.ts`. `dotenv` n'est pas disponible dans l'image de production et les variables d'environnement sont injectées par le système d'orchestration (K8s). | --- ## 4. Runtime config du frontend (Next.js) Les applications Next.js déployées en conteneur ont deux sources de configuration : les variables `NEXT_PUBLIC_*` (compilées au build) et les variables injectées à l'exécution via `window.__RUNTIME_CONFIG__`. Il faut impérativement aligner les noms de variables entre `docker-entrypoint.sh` et le déploiement Kubernetes. ### Règles pour la runtime config - L'`entrypoint.sh` du frontend doit lire les variables **telles qu'elles sont définies dans le déploiement K8s** (`NEXT_PUBLIC_API_URL`, `KEYCLOAK_PUBLIC_URL`, etc.), et **non** des alias inventés localement (`API_URL`, `KEYCLOAK_URL`…). - Toute URL susceptible de changer selon l'environnement **sans rebuild** de l'image (ex: URL Keycloak) doit être injectée via `window.__RUNTIME_CONFIG__` et **non** lue via `process.env.NEXT_PUBLIC_*`. - Documenter dans le `.env.example` de chaque service quelles variables sont compilées au build (`NEXT_PUBLIC_*`) et lesquelles sont injectées à l'exécution. - En cas de doublon entre une variable `NEXT_PUBLIC_*` et une variable runtime, documenter explicitement laquelle a la priorité et pourquoi. > ⚠️ Un `entrypoint.sh` qui lit des variables inexistantes laisse `window.__RUNTIME_CONFIG__` avec les valeurs par défaut hardcodées (`localhost`, `preprod`…), ce qui est indétectable sans logs. --- ## 5. Intégration S3 et Object Storage Les adaptateurs S3 doivent gérer correctement les URLs d'endpoint pour éviter des erreurs de connectivité silencieuses. ### Règles pour les endpoints S3 - Ne **jamais** préfixer mécaniquement `https://` sur une variable d'endpoint : si la variable contient déjà le protocole, la double-préfixation produit une URL invalide (`https://https://…`) non détectable par les linters. - L'adaptateur doit **détecter** si l'endpoint contient déjà un protocole, **parser** l'URL pour en déduire le port (`443` pour `https`, `80` pour `http`), et **ne pas forcer** le port `9000` par défaut (qui est le port MinIO local, non le port OVH Object Storage). - Documenter dans le `.env.example` si la variable `MINIO_ENDPOINT` / `S3_ENDPOINT` doit ou non inclure le protocole, le port et le chemin. - Préférer les variables classiques S3 du type : `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, etc. --- ## 6. Authentification et flux OAuth / Keycloak > Voir aussi [Authentification — Concepts & Flow](/v1.0/dev/03-authentication-overview) pour le flux OAuth général. Les règles ci-dessous sont des **pièges concrets** rencontrés sur des services en production. ### 6.1 `redirect_uri` Le `redirect_uri` envoyé dans la requête d'autorisation doit être **strictement identique** à celui utilisé lors de l'échange de code côté serveur. Toute divergence provoque un rejet Keycloak. Le serveur doit utiliser le `redirect_uri` **fourni par le client** lors du callback, et non une valeur hardcodée. ### 6.2 Clés `sessionStorage` Toutes les clés `sessionStorage` utilisées dans le flux OAuth (`realm`, `client_id`, `state`, `code_verifier`…) doivent être déclarées dans un **fichier de constantes partagé** entre tous les modules impliqués. L'utilisation de chaînes littérales dispersées est interdite. ### 6.3 `login_hint` Lorsque l'email de l'utilisateur est connu avant la redirection vers Keycloak, transmettre le paramètre standard OIDC `login_hint` pour pré-remplir le formulaire Keycloak et éviter une double saisie. ### 6.4 Multi-organisations (Discovery) Si l'API Discovery peut retourner plusieurs comptes pour un même email (plusieurs realms Keycloak), le frontend doit afficher un écran de **sélection d'organisation** avant de rediriger. Ne jamais prendre aveuglément `users[0]` si la réponse peut contenir plusieurs entrées. - Vérifier la présence d'utilisateurs avec `users?.length > 0` et **non** avec un champ `found` qui peut ne pas exister selon la version de l'API. - Vérifier systématiquement le **nom exact** du champ d'identifiant retourné par l'API (`customer_wid` vs `network_id`, `customer_id` vs `customer_wid`…) et le documenter dans le contrat d'API. ### 6.5 URL de Keycloak côté serveur La variable `KEYCLOAK_URL` (URL interne ou publique pour les appels server-side) doit être **explicitement définie** dans la configuration K8s. Sans elle, les appels tombent sur `localhost:8080` et échouent silencieusement. Documenter dans le `.env.example` la différence entre `KEYCLOAK_URL` (server-side) et `NEXT_PUBLIC_KEYCLOAK_URL` / `KEYCLOAK_PUBLIC_URL` (client-side / runtime). --- ## 7. Migrations Prisma (au-delà du runtime) Les migrations de base de données doivent être gérées de manière déterministe et reproductible entre les environnements. ### Règles pour les migrations Prisma - Le répertoire `prisma/migrations/` doit contenir une **migration initiale** générée par `prisma migrate dev` qui crée l'intégralité du schéma. Les scripts SQL en vrac non gérés par Prisma ne sont pas acceptables. - Les migrations spécifiques (ex: index FTS, ajout de colonnes) doivent être encapsulées dans des **migrations Prisma dédiées**, et non sous forme de fichiers SQL isolés. - `prisma` doit figurer dans les `dependencies` (non `devDependencies`) pour que `prisma migrate deploy` soit disponible dans l'image de production. - L'`entrypoint.sh` exécute `prisma migrate deploy` avant tout démarrage de l'application — voir [section 2](#2-dockerfile-et-migrations-prisma). - Ne jamais importer `dotenv/config` dans `prisma.config.ts` : les variables d'environnement sont injectées par K8s. 4f:Tcda, # Glossaire de l'hébergement ## Concepts généraux - **PaaS** (Platform as a Service) : tu codes ton app, la plateforme l'héberge — elle fournit l'infra, l'OS, le runtime et le pipeline de déploiement. Opposé : IaaS (tu gères les VMs). - **Kubernetes (K8s)** : orchestrateur qui fait tourner des conteneurs Docker sur un cluster de serveurs. Wakastart est bâti dessus. - **Pod** : la plus petite unité K8s, contient 1+ conteneurs. Un ServiceInstance avec `replicas: 3` donne 3 pods. - **Cluster** : un ensemble de serveurs (nœuds) qui tournent K8s ensemble. Wakastart opère plusieurs clusters (un par environnement majeur). - **Namespace** : cloison d'isolation dans un cluster. Chaque environnement Wakastart a son namespace dédié — c'est ce qui isole les ressources entre apps et entre environnements. ## Images et registry - **Docker image** : un paquet figé qui contient ton code + ses dépendances + l'OS minimal pour tourner. Reproductible. - **Registry** : un stockage d'images Docker. Wakastart fournit un registry privé par app — tes images n'en sortent pas. - **Tag** : un nom de version d'une image (ex: `:latest`, `:1.2.3`, `:abc123`). - **Quota** : la place maximale que les images d'une app peuvent occuper dans le registre, fixée par un administrateur de la plateforme. Quand elle est atteinte, Wakastart refuse de lancer un nouveau build. Rien n'est limité dans le registre lui-même. Voir [Quota du registre](26-builds#quota-du-registre). - **Purge** : la suppression automatique, chaque nuit, des images des builds les plus anciens. Désactivée par défaut, activée app par app. Les images déployées ou encore utilisées sont toujours gardées. Voir [Conservation des images](26-builds#conservation-des-images-purge-automatique). ## Stockage - **Bucket S3** : conteneur de fichiers (objets) accessible via HTTP, identifié par un nom unique. Pas de hiérarchie de dossiers réelle, juste des clés. - **BDD relationnelle** (PostgreSQL, MySQL) : tables, colonnes, jointures, transactions ACID. Pour de la donnée transactionnelle. - **BDD NoSQL document** (MongoDB) : collections de documents JSON, schema flexible. Pour des objets imbriqués évolutifs. - **Key-value store** (Valkey/Redis) : `SET key value` / `GET key`. Pour du cache, des sessions, des compteurs en mémoire. ## Sécurité - **Secret manager** : coffre-fort chiffré qui stocke les credentials sensibles (mots de passe BDD, clés API, certificats). Wakastart en fournit un, isolé par app. Tu n'y accèdes jamais directement : la plateforme injecte les secrets dans tes pods au démarrage. ## Réseau - **Gateway** : entrée de la plateforme pour le trafic HTTP entrant. C'est elle qui termine le TLS (certificats) et applique les règles de routage HttpRoute. - **HttpRoute** : règle de routage qui dit "ce chemin → ce service". - **DNS** : système qui traduit les noms (`api.exemple.com`) en IP. Wakastart provisionne les enregistrements CNAME chez le registrar du domaine plateforme. ## CI/CD - **CI** (Continuous Integration) : tests automatiques sur chaque commit. Pas géré par Wakastart (tu utilises GitHub Actions, Jenkins, etc.). - **CD** (Continuous Deployment) : déploiement automatique après build réussi. Géré par Wakastart via auto-deploy. 5:["$","$L10",null,{"locale":"fr","versions":[{"id":"v1.0","label":"1.0","date":"2026-05-19","status":"stable"}],"sections":[{"id":"user","label":"Utilisateur","icon":"BookOpen"},{"id":"dev","label":"Développeur","icon":"Code2"}],"latestVersion":"v1.0","currentVersion":"v1.0","searchEntries":[{"id":"v1.0-user-01-getting-started-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"01-getting-started","chapterTitle":"Connexion et authentification","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous vous connectez pour la première fois à WakaStart\n- Vous souhaitez changer d'organisation ou de compte\n- Vous avez oublié votre mot de passe","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-01-getting-started-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"01-getting-started","chapterTitle":"Connexion et authentification","heading":"Se connecter à WakaStart","snippet":"","anchor":"se-connecter-wakastart"},{"id":"v1.0-user-01-getting-started-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"01-getting-started","chapterTitle":"Connexion et authentification","heading":"Étape 1 — Saisissez votre adresse e-mail professionnelle","snippet":"Sur la page d'accueil, entrez l'adresse e-mail avec laquelle vous avez été invité. Cliquez sur **Continuer**.\n\nSi votre adresse n'est pas reconnue, vous verrez le message : \"Aucun compte trouvé pour c","anchor":"tape-1-saisissez-votre-adresse-e-mail-professionnelle"},{"id":"v1.0-user-01-getting-started-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"01-getting-started","chapterTitle":"Connexion et authentification","heading":"Étape 2 — Choisissez votre organisation (si vous en avez plusieurs)","snippet":"Si votre adresse e-mail est rattachée à plusieurs organisations, une liste s'affiche. Cliquez sur l'organisation dans laquelle vous souhaitez travailler.","anchor":"tape-2-choisissez-votre-organisation-si-vous-en-avez-plusieurs"},{"id":"v1.0-user-01-getting-started-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"01-getting-started","chapterTitle":"Connexion et authentification","heading":"Étape 3 — Saisissez votre mot de passe","snippet":"Vous êtes redirigé vers la page de connexion de votre organisation. Entrez votre mot de passe et validez. Vous arrivez ensuite directement sur votre tableau de bord.","anchor":"tape-3-saisissez-votre-mot-de-passe"},{"id":"v1.0-user-01-getting-started-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"01-getting-started","chapterTitle":"Connexion et authentification","heading":"Premier accès","snippet":"Lors de votre toute première connexion, un message de bienvenue s'affiche pour vous guider dans la découverte de la plateforme. Vous pouvez le fermer à tout moment en cliquant sur **Ignorer**.","anchor":"premier-accs"},{"id":"v1.0-user-01-getting-started-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"01-getting-started","chapterTitle":"Connexion et authentification","heading":"Options pratiques","snippet":"- **Basculer entre thème clair et sombre** : utilisez le bouton en haut à droite de la page de connexion selon vos préférences d'affichage.","anchor":"options-pratiques"},{"id":"v1.0-user-01-getting-started-7","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"01-getting-started","chapterTitle":"Connexion et authentification","heading":"Aller plus loin","snippet":"- [Découvrir le tableau de bord](./dashboard)\n- [Modifier vos informations personnelles](./profile)","anchor":"aller-plus-loin"},{"id":"v1.0-user-02-dashboard-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"02-dashboard","chapterTitle":"Tableau de bord principal","heading":"Ce que vous voyez sur le tableau de bord","snippet":"","anchor":"ce-que-vous-voyez-sur-le-tableau-de-bord"},{"id":"v1.0-user-02-dashboard-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"02-dashboard","chapterTitle":"Tableau de bord principal","heading":"Les compteurs clés","snippet":"En haut de la page, plusieurs compteurs affichent en un coup d'œil les chiffres importants de votre plateforme : nombre de **Partenaires**, de **Réseaux**, de **Clients**, d'**Utilisateurs** et d'**Ap","anchor":"les-compteurs-cls"},{"id":"v1.0-user-02-dashboard-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"02-dashboard","chapterTitle":"Tableau de bord principal","heading":"Le fil d'activité récente","snippet":"En dessous des compteurs, vous retrouvez les 5 dernières actions importantes (créations, modifications de clients ou d'utilisateurs). Un bouton **Rafraîchir** vous permet de mettre à jour la liste à l","anchor":"le-fil-dactivit-rcente"},{"id":"v1.0-user-02-dashboard-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"02-dashboard","chapterTitle":"Tableau de bord principal","heading":"L'en-tête du tableau de bord","snippet":"La barre en haut de l'écran est toujours visible et vous donne accès aux fonctions essentielles :\n\n- **Votre prénom** : message de bienvenue personnalisé\n- **Votre solde de crédits** : mis à jour auto","anchor":"len-tte-du-tableau-de-bord"},{"id":"v1.0-user-02-dashboard-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"02-dashboard","chapterTitle":"Tableau de bord principal","heading":"Le filtre global","snippet":"Une barre de navigation contextuelle apparaît en haut de chaque page. Elle vous permet de restreindre l'affichage à un **Partenaire**, un **Réseau** et/ou un **Client** spécifique.\n\nLa plupart des lis","anchor":"le-filtre-global"},{"id":"v1.0-user-02-dashboard-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"02-dashboard","chapterTitle":"Tableau de bord principal","heading":"Aller plus loin","snippet":"- [Gérer vos partenaires](./partners)\n- [Gérer vos clients](./customers)\n- [Modifier vos préférences personnelles](./profile)","anchor":"aller-plus-loin"},{"id":"v1.0-user-03-partners-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"03-partners","chapterTitle":"Partenaires","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **référencer une nouvelle société partenaire** sur la plateforme\n- Vous voulez **consulter ou modifier les informations** d'un partenaire existant\n- Vous devez **suivre le solde d'heu","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-03-partners-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"03-partners","chapterTitle":"Partenaires","heading":"Accéder à la liste des partenaires","snippet":"Depuis le menu principal à gauche, cliquez sur **Organisation** puis **Partenaires**.\n\nLa liste affiche, pour chaque partenaire : son **nom**, l'**entité juridique** associée, son **statut** (Actif, I","anchor":"accder-la-liste-des-partenaires"},{"id":"v1.0-user-03-partners-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"03-partners","chapterTitle":"Partenaires","heading":"Créer un partenaire","snippet":"1. Cliquez sur **+ Nouveau partenaire** en haut à droite.\n2. Renseignez les informations demandées :\n - **Nom** : nom commercial du partenaire (obligatoire, 100 caractères max)\n - **Description** ","anchor":"crer-un-partenaire"},{"id":"v1.0-user-03-partners-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"03-partners","chapterTitle":"Partenaires","heading":"Modifier un partenaire","snippet":"Cliquez sur l'icône crayon en face du partenaire souhaité. Le formulaire est identique à la création, à l'exception de l'entité juridique qui ne peut plus être modifiée après la création initiale.","anchor":"modifier-un-partenaire"},{"id":"v1.0-user-03-partners-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"03-partners","chapterTitle":"Partenaires","heading":"Supprimer un partenaire","snippet":"Cliquez sur l'icône corbeille, puis confirmez. La suppression est définitive.","anchor":"supprimer-un-partenaire"},{"id":"v1.0-user-03-partners-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"03-partners","chapterTitle":"Partenaires","heading":"Consulter la fiche détail d'un partenaire","snippet":"Cliquez sur le **nom** du partenaire dans la liste pour accéder à sa fiche complète. Vous y retrouvez les applications et les réseaux qui lui sont rattachés.","anchor":"consulter-la-fiche-dtail-dun-partenaire"},{"id":"v1.0-user-03-partners-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"03-partners","chapterTitle":"Partenaires","heading":"Aller plus loin","snippet":"- [Gérer les réseaux d'un partenaire](./networks)\n- [Gérer les entités juridiques](./entities)","anchor":"aller-plus-loin"},{"id":"v1.0-user-04-networks-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **créer un nouveau réseau** pour regrouper des clients\n- Vous voulez **configurer les paramètres** d'un réseau existant (langue, thème, sous-domaine)\n- Vous devez **consulter les clie","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-04-networks-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Accéder à la liste des réseaux","snippet":"Depuis le menu principal à gauche, cliquez sur **Organisation** puis **Réseaux**.\n\nLa liste affiche, pour chaque réseau : son **nom**, l'**application** propriétaire, son **statut** et son **sous-doma","anchor":"accder-la-liste-des-rseaux"},{"id":"v1.0-user-04-networks-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Créer un réseau","snippet":"1. Cliquez sur **+ Nouveau réseau** en haut à droite.\n2. Renseignez les informations demandées :\n - **Nom** : le nom du réseau tel qu'il apparaîtra dans l'interface (obligatoire)\n - **Description*","anchor":"crer-un-rseau"},{"id":"v1.0-user-04-networks-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Configurer un réseau existant","snippet":"Cliquez sur l'icône engrenage en face du réseau pour accéder à sa configuration détaillée. Vous pourrez y gérer les clients rattachés, les fonctionnalités activées et les options avancées.","anchor":"configurer-un-rseau-existant"},{"id":"v1.0-user-04-networks-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Supprimer un réseau","snippet":"Cliquez sur l'icône corbeille, puis confirmez. Assurez-vous au préalable que tous les clients du réseau sont soit migrés soit supprimés.","anchor":"supprimer-un-rseau"},{"id":"v1.0-user-04-networks-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Redirections d'URL","snippet":"> Une redirection d'URL vous permet de faire pointer un sous-domaine personnalisé vers une page précise de votre application — pratique pour donner une adresse mémorisable à un réseau, sans exposer l'","anchor":"redirections-durl"},{"id":"v1.0-user-04-networks-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Quand utilisez-vous cette fonctionnalité ?","snippet":"- Vous voulez **offrir une adresse dédiée** à votre réseau, qui redirige vers une page précise de l'application (landing, portail de connexion, etc.)\n- Vous devez **changer l'environnement ou la page ","anchor":"quand-utilisez-vous-cette-fonctionnalit-"},{"id":"v1.0-user-04-networks-7","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Créer une redirection","snippet":"1. Depuis la configuration détaillée du réseau, ouvrez l'onglet **Redirections d'URL**.\n2. Cliquez sur **+ Nouvelle redirection**.\n3. Renseignez le **bloc Source** :\n - **Domaine** : un domaine pers","anchor":"crer-une-redirection"},{"id":"v1.0-user-04-networks-8","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Modifier la destination","snippet":"Vous pouvez à tout moment changer la **route**, l'**environnement**, le **chemin** ou les **paramètres de requête** ciblés, sans recréer la redirection ni impacter l'adresse source déjà communiquée à ","anchor":"modifier-la-destination"},{"id":"v1.0-user-04-networks-9","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Suivre le statut d'une redirection","snippet":"| Statut affiché | Signification |\n|-----------------|----------------|\n| **En attente** | La redirection vient d'être créée, en attente de traitement |\n| **En cours de création** | Les ressources tec","anchor":"suivre-le-statut-dune-redirection"},{"id":"v1.0-user-04-networks-10","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Supprimer une redirection","snippet":"Cliquez sur l'icône corbeille en face de la redirection, puis confirmez. La suppression n'affecte jamais la route ou l'environnement ciblés par la destination.","anchor":"supprimer-une-redirection"},{"id":"v1.0-user-04-networks-11","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"04-networks","chapterTitle":"Réseaux","heading":"Aller plus loin","snippet":"- [Gérer les clients d'un réseau](./customers)\n- [Activer des fonctionnalités pour un réseau](./settings)\n- [Comprendre le mécanisme technique des redirections d'URL](../dev/url-redirects)","anchor":"aller-plus-loin"},{"id":"v1.0-user-05-customers-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous voulez **ajouter une nouvelle organisation cliente** à votre réseau\n- Vous souhaitez **modifier les informations** d'un client existant\n- Vous devez **suspendre ou supprimer** un client\n- Vous ","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-05-customers-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Accéder à la liste des clients","snippet":"Depuis le menu principal à gauche, cliquez sur **Organisation** puis **Clients**.\n\nLa liste affiche, pour chaque client : son **nom**, le **réseau** d'appartenance, l'**application** associée, son **s","anchor":"accder-la-liste-des-clients"},{"id":"v1.0-user-05-customers-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Créer un client","snippet":"> Avant de créer un client, assurez-vous d'avoir sélectionné un réseau dans le filtre global en haut de la page. Sans cette sélection, la création est bloquée.\n\n1. Cliquez sur **+ Nouveau client** en ","anchor":"crer-un-client"},{"id":"v1.0-user-05-customers-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Configurer un client existant","snippet":"Cliquez sur l'icône engrenage en face du client pour accéder à sa page de configuration complète : thème, domaines, fonctionnalités activées, et options avancées.","anchor":"configurer-un-client-existant"},{"id":"v1.0-user-05-customers-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Supprimer un client","snippet":"Cliquez sur l'icône corbeille. Si le client possède des données associées (utilisateurs, équipes, profils...), un récapitulatif vous est présenté. Pour confirmer la suppression, vous devrez saisir le ","anchor":"supprimer-un-client"},{"id":"v1.0-user-05-customers-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Redirections d'URL","snippet":"> Une redirection d'URL vous permet de faire pointer un sous-domaine personnalisé vers une page précise de votre application — pratique pour donner une adresse mémorisable à un client, sans exposer l'","anchor":"redirections-durl"},{"id":"v1.0-user-05-customers-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Quand utilisez-vous cette fonctionnalité ?","snippet":"- Vous voulez **offrir une adresse dédiée** à ce client, qui redirige vers une page précise de l'application (portail de connexion, espace personnalisé, etc.)\n- Vous devez **changer l'environnement ou","anchor":"quand-utilisez-vous-cette-fonctionnalit-"},{"id":"v1.0-user-05-customers-7","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Créer une redirection","snippet":"1. Depuis la page de configuration du client, ouvrez l'onglet **Redirections d'URL**.\n2. Cliquez sur **+ Nouvelle redirection**.\n3. Renseignez le **bloc Source** :\n - **Domaine** : un domaine person","anchor":"crer-une-redirection"},{"id":"v1.0-user-05-customers-8","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Modifier la destination","snippet":"Vous pouvez à tout moment changer la **route**, l'**environnement**, le **chemin** ou les **paramètres de requête** ciblés, sans recréer la redirection ni impacter l'adresse source déjà communiquée à ","anchor":"modifier-la-destination"},{"id":"v1.0-user-05-customers-9","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Suivre le statut d'une redirection","snippet":"| Statut affiché | Signification |\n|-----------------|----------------|\n| **En attente** | La redirection vient d'être créée, en attente de traitement |\n| **En cours de création** | Les ressources tec","anchor":"suivre-le-statut-dune-redirection"},{"id":"v1.0-user-05-customers-10","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Supprimer une redirection","snippet":"Cliquez sur l'icône corbeille en face de la redirection, puis confirmez. La suppression n'affecte jamais la route ou l'environnement ciblés par la destination.","anchor":"supprimer-une-redirection"},{"id":"v1.0-user-05-customers-11","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"05-customers","chapterTitle":"Clients","heading":"Aller plus loin","snippet":"- [Gérer les utilisateurs d'un client](./users)\n- [Organiser les utilisateurs en équipes](./teams)\n- [Activer des fonctionnalités pour un client](./settings)\n- [Comprendre le mécanisme technique des r","anchor":"aller-plus-loin"},{"id":"v1.0-user-06-users-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"06-users","chapterTitle":"Utilisateurs","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous voulez **inviter un nouvel administrateur** sur la plateforme\n- Vous devez **modifier le niveau d'accès** d'un utilisateur existant\n- Vous souhaitez **activer ou désactiver** un compte utilisat","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-06-users-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"06-users","chapterTitle":"Utilisateurs","heading":"Accéder à la liste des utilisateurs","snippet":"Depuis le menu principal à gauche, cliquez sur **Organisation** puis **Utilisateurs**.\n\nLa liste affiche, pour chaque utilisateur : son **adresse e-mail**, son **nom complet**, le **Client** auquel il","anchor":"accder-la-liste-des-utilisateurs"},{"id":"v1.0-user-06-users-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"06-users","chapterTitle":"Utilisateurs","heading":"Créer un utilisateur","snippet":"1. Cliquez sur **+ Nouvel utilisateur** en haut à droite.\n2. Renseignez les informations dans les différents onglets :","anchor":"crer-un-utilisateur"},{"id":"v1.0-user-06-users-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"06-users","chapterTitle":"Utilisateurs","heading":"Onglet Général","snippet":"- **Client** : le Client auquel cet utilisateur appartient\n- **Adresse e-mail** : l'adresse qui servira d'identifiant de connexion\n- **Prénom** et **Nom**\n- **Mot de passe temporaire** : facultatif — ","anchor":"onglet-gnral"},{"id":"v1.0-user-06-users-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"06-users","chapterTitle":"Utilisateurs","heading":"Onglet Permissions","snippet":"- **Niveau d'administration** : définit ce que l'utilisateur peut gérer sur la plateforme. Vous ne pouvez pas attribuer un niveau supérieur au vôtre.\n- **Niveau utilisateur** : niveau d'accès dans l'a","anchor":"onglet-permissions"},{"id":"v1.0-user-06-users-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"06-users","chapterTitle":"Utilisateurs","heading":"Onglet HDS (données de santé)","snippet":"Si votre plateforme est certifiée HDS, vous pouvez attribuer des rôles spécifiques à cet utilisateur pour contrôler son accès aux données de santé :\n\n- **Administrateur HDS** — gestion globale des don","anchor":"onglet-hds-donnes-de-sant"},{"id":"v1.0-user-06-users-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"06-users","chapterTitle":"Utilisateurs","heading":"Onglet Profils","snippet":"Sélectionnez les profils applicatifs à attribuer à cet utilisateur (les profils définissent ses droits dans les applications).\n\n3. Cliquez sur **Créer**.","anchor":"onglet-profils"},{"id":"v1.0-user-06-users-7","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"06-users","chapterTitle":"Utilisateurs","heading":"Gérer les utilisateurs d'un Client","snippet":"En accédant à la fiche d'un client, vous pouvez gérer directement les comptes de ses utilisateurs via l'onglet **Utilisateurs**. Vous pouvez :\n\n- **Désactiver** ou **réactiver** un compte\n- **Réinitia","anchor":"grer-les-utilisateurs-dun-client"},{"id":"v1.0-user-06-users-8","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"06-users","chapterTitle":"Utilisateurs","heading":"Aller plus loin","snippet":"- [Créer et gérer les profils applicatifs](./profiles-rights)\n- [Organiser les utilisateurs en équipes](./teams)\n- [Gérer les rôles HDS](./hds)","anchor":"aller-plus-loin"},{"id":"v1.0-user-07-teams-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"07-teams","chapterTitle":"Équipes","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous voulez **créer un groupe de travail** au sein d'un Client\n- Vous souhaitez **affecter des utilisateurs** à une équipe existante\n- Vous devez **définir des niveaux d'accès différents** pour des ","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-07-teams-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"07-teams","chapterTitle":"Équipes","heading":"Accéder à la liste des équipes","snippet":"Depuis le menu principal à gauche, cliquez sur **Organisation** puis **Équipes**.\n\nLa liste affiche, pour chaque équipe : son **nom**, sa **description**, le **client** d'appartenance et le **nombre d","anchor":"accder-la-liste-des-quipes"},{"id":"v1.0-user-07-teams-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"07-teams","chapterTitle":"Équipes","heading":"Créer une équipe","snippet":"1. Cliquez sur **+ Nouvelle équipe** en haut à droite.\n2. Renseignez le **nom** de l'équipe et une **description** courte.\n3. Cliquez sur **Créer**.","anchor":"crer-une-quipe"},{"id":"v1.0-user-07-teams-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"07-teams","chapterTitle":"Équipes","heading":"Gérer les membres d'une équipe","snippet":"1. Cliquez sur l'icône **Gérer les membres** (personnes) en face de l'équipe.\n2. La liste de tous les utilisateurs du client s'affiche.\n3. Pour chaque utilisateur, vous pouvez :\n - **Cocher la case*","anchor":"grer-les-membres-dune-quipe"},{"id":"v1.0-user-07-teams-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"07-teams","chapterTitle":"Équipes","heading":"Modifier ou supprimer une équipe","snippet":"- Cliquez sur l'icône **crayon** pour modifier le nom ou la description de l'équipe.\n- Cliquez sur l'icône **corbeille** pour supprimer l'équipe. Les utilisateurs membres ne sont pas supprimés, seulem","anchor":"modifier-ou-supprimer-une-quipe"},{"id":"v1.0-user-07-teams-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"07-teams","chapterTitle":"Équipes","heading":"Aller plus loin","snippet":"- [Gérer les utilisateurs d'un client](./users)\n- [Créer des profils applicatifs](./profiles-rights)","anchor":"aller-plus-loin"},{"id":"v1.0-user-08-applications-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"08-applications","chapterTitle":"Applications","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **référencer une nouvelle application** sur la plateforme\n- Vous voulez **consulter le statut de déploiement** d'une application\n- Vous devez **configurer les paramètres** d'une appli","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-08-applications-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"08-applications","chapterTitle":"Applications","heading":"Accéder à la liste des applications","snippet":"Depuis le menu principal à gauche, cliquez sur **Applications**.\n\nLa liste affiche, pour chaque application : son **nom**, son **type** (Application, Module ou Service), le **partenaire propriétaire**","anchor":"accder-la-liste-des-applications"},{"id":"v1.0-user-08-applications-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"08-applications","chapterTitle":"Applications","heading":"Créer une application","snippet":"1. Cliquez sur **+ Nouvelle application** en haut à droite.\n2. Renseignez les informations :\n - **Partenaire propriétaire** : le partenaire à qui cette application appartient\n - **Nom** : le nom d","anchor":"crer-une-application"},{"id":"v1.0-user-08-applications-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"08-applications","chapterTitle":"Applications","heading":"Supprimer une application","snippet":"Cliquez sur l'icône corbeille. Pour confirmer, vous devrez saisir le **nom exact** de l'application. Cette opération est irréversible.","anchor":"supprimer-une-application"},{"id":"v1.0-user-08-applications-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"08-applications","chapterTitle":"Applications","heading":"Gérer les documents légaux","snippet":"Lorsqu'une application est marquée comme commerciale, vous pouvez rédiger et gérer ses documents légaux (conditions générales, politique de confidentialité, etc.) via l'éditeur de documents intégré.\n\n","anchor":"grer-les-documents-lgaux"},{"id":"v1.0-user-08-applications-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"08-applications","chapterTitle":"Applications","heading":"Gérer l'infrastructure d'une application","snippet":"Cliquez sur l'icône **fusée** en face d'une application pour accéder à sa vue infrastructure. Vous y trouverez :\n\n- **Architecture** : les services, dépôts, dépendances et adresses associés\n- **Builds","anchor":"grer-linfrastructure-dune-application"},{"id":"v1.0-user-08-applications-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"08-applications","chapterTitle":"Applications","heading":"Consulter les URLs par environnement","snippet":"Cliquez sur l'icône **Voir les URLs** (lien externe) en face d'une application pour ouvrir la fenêtre **URLs par environnement**. Elle liste, pour chaque environnement (dev, staging, prod) : son nom, ","anchor":"consulter-les-urls-par-environnement"},{"id":"v1.0-user-08-applications-7","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"08-applications","chapterTitle":"Applications","heading":"Aller plus loin","snippet":"- [Créer des profils et des droits pour une application](./profiles-rights)\n- [Gérer les clés d'accès programmatique](./api-keys)\n- [Consulter les journaux d'audit d'une application](./audit-logs)","anchor":"aller-plus-loin"},{"id":"v1.0-user-09-profiles-rights-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"09-profiles-rights","chapterTitle":"Profils et droits","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **créer un nouveau profil** pour un groupe d'utilisateurs ayant les mêmes besoins d'accès\n- Vous voulez **modifier les droits** d'un profil existant\n- Vous devez **attribuer un profil","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-09-profiles-rights-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"09-profiles-rights","chapterTitle":"Profils et droits","heading":"Accéder à la liste des profils","snippet":"Depuis le menu principal à gauche, cliquez sur **Applications** puis **Profils**.\n\nLa liste affiche, pour chaque profil : son **nom**, sa **description** et l'**application** à laquelle il appartient.","anchor":"accder-la-liste-des-profils"},{"id":"v1.0-user-09-profiles-rights-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"09-profiles-rights","chapterTitle":"Profils et droits","heading":"Créer un profil","snippet":"1. Cliquez sur **+ Nouveau profil** en haut à droite.\n2. Onglet **Général** : renseignez le **nom** du profil, une **description**, et sélectionnez l'**application** concernée (verrouillée en modifica","anchor":"crer-un-profil"},{"id":"v1.0-user-09-profiles-rights-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"09-profiles-rights","chapterTitle":"Profils et droits","heading":"Les droits disponibles","snippet":"L'onglet AppRights affiche une liste de cases à cocher propre à l'application sélectionnée — elle n'est pas figée : certains droits correspondent à des catégories historiques larges, d'autres sont des","anchor":"les-droits-disponibles"},{"id":"v1.0-user-09-profiles-rights-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"09-profiles-rights","chapterTitle":"Profils et droits","heading":"Modifier ou supprimer un profil","snippet":"- Cliquez sur l'icône **crayon** pour modifier un profil existant.\n- Cliquez sur l'icône **corbeille** pour le supprimer. Les utilisateurs ayant ce profil perdront les droits associés.\n\n> Les profils ","anchor":"modifier-ou-supprimer-un-profil"},{"id":"v1.0-user-09-profiles-rights-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"09-profiles-rights","chapterTitle":"Profils et droits","heading":"Attribuer un profil à un utilisateur","snippet":"L'attribution se fait depuis la fiche de l'utilisateur, onglet **Profils**. Vous pouvez ajouter ou retirer des profils à tout moment, l'effet est immédiat.","anchor":"attribuer-un-profil-un-utilisateur"},{"id":"v1.0-user-09-profiles-rights-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"09-profiles-rights","chapterTitle":"Profils et droits","heading":"Aller plus loin","snippet":"- [Gérer les utilisateurs](./users)\n- [Gérer les clés d'accès programmatique](./api-keys)","anchor":"aller-plus-loin"},{"id":"v1.0-user-10-api-keys-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"10-api-keys","chapterTitle":"Clés API","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **connecter un outil externe** à WakaStart (outil de déploiement, logiciel de supervision, script d'automatisation)\n- Vous devez **créer un compte technique avec des droits limités** ","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-10-api-keys-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"10-api-keys","chapterTitle":"Clés API","heading":"Accéder à la liste des clés API","snippet":"Depuis le menu principal à gauche, cliquez sur **Applications** puis **Clés API**. Les clés existantes s'affichent sous forme de **cartes** (pas un tableau) : chaque carte indique le nom et son statut","anchor":"accder-la-liste-des-cls-api"},{"id":"v1.0-user-10-api-keys-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"10-api-keys","chapterTitle":"Clés API","heading":"Créer une clé API (compte technique)","snippet":"1. Cliquez sur **+ Nouvelle clé** en haut à droite. La fenêtre précise qu'il s'agit d'un principal autonome, indépendant de tout utilisateur.\n2. Renseignez les informations obligatoires, dans l'ordre ","anchor":"crer-une-cl-api-compte-technique"},{"id":"v1.0-user-10-api-keys-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"10-api-keys","chapterTitle":"Clés API","heading":"Révoquer une clé API","snippet":"Cliquez sur l'icône corbeille en face de la clé. La révocation est immédiate et irréversible.","anchor":"rvoquer-une-cl-api"},{"id":"v1.0-user-10-api-keys-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"10-api-keys","chapterTitle":"Clés API","heading":"Aller plus loin","snippet":"- [Gérer les profils et droits](./profiles-rights)\n- [Consulter les journaux d'audit](./audit-logs)","anchor":"aller-plus-loin"},{"id":"v1.0-user-27-tickets-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"27-tickets","chapterTitle":"Gestion des tickets","heading":"Créer un ticket","snippet":"Depuis la liste des tickets d'une App, ouvrez le formulaire de création. Un ticket comporte :\n\n- **Titre** et **description** (éditeur enrichi, vous pouvez coller des images directement dans la descri","anchor":"crer-un-ticket"},{"id":"v1.0-user-27-tickets-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"27-tickets","chapterTitle":"Gestion des tickets","heading":"Statuts","snippet":"Un ticket suit l'un des 9 statuts suivants :\n\n| Statut | Signification |\n|--------|----------------|\n| Plus tard | Signalé mais pas encore planifié |\n| Ouvert | Nouveau ticket, pas encore pris en char","anchor":"statuts"},{"id":"v1.0-user-27-tickets-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"27-tickets","chapterTitle":"Gestion des tickets","heading":"Assignation","snippet":"Un ticket peut être assigné à un administrateur habilité sur l'App concernée. La liste des personnes éligibles à l'assignation est calculée dynamiquement en fonction des droits sur l'application.","anchor":"assignation"},{"id":"v1.0-user-27-tickets-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"27-tickets","chapterTitle":"Gestion des tickets","heading":"Visibilité : Waka ou Client","snippet":"Chaque ticket porte une visibilité :\n\n- **Waka** : visible uniquement par les équipes Wakastellar.\n- **Client** : visible également par le client (Customer) concerné.\n\nCette visibilité peut être modif","anchor":"visibilit-waka-ou-client"},{"id":"v1.0-user-27-tickets-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"27-tickets","chapterTitle":"Gestion des tickets","heading":"Commentaires","snippet":"Chaque ticket dispose d'un fil de commentaires : créer, modifier et supprimer un commentaire sont possibles (la suppression est logique, jamais physique — le commentaire reste tracé côté plateforme).","anchor":"commentaires"},{"id":"v1.0-user-27-tickets-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"27-tickets","chapterTitle":"Gestion des tickets","heading":"Pièces jointes","snippet":"Vous pouvez joindre des fichiers à un ticket (jusqu'à 20 pièces jointes par ticket). Chaque pièce jointe suit ce cycle :\n\n1. Demande d'upload (URL S3 présignée).\n2. Upload du fichier, puis confirmatio","anchor":"pices-jointes"},{"id":"v1.0-user-27-tickets-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"27-tickets","chapterTitle":"Gestion des tickets","heading":"Historique","snippet":"Chaque ticket conserve un historique des changements (statut, assignation, priorité, etc.), avec les personnes concernées affichées par leur nom plutôt que par leur identifiant technique.","anchor":"historique"},{"id":"v1.0-user-27-tickets-7","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"27-tickets","chapterTitle":"Gestion des tickets","heading":"Suppression","snippet":"La suppression d'un ticket est réservée à son auteur, et reste une suppression logique (le ticket est masqué, pas détruit).","anchor":"suppression"},{"id":"v1.0-user-27-tickets-8","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"27-tickets","chapterTitle":"Gestion des tickets","heading":"Aller plus loin","snippet":"- [Applications](08-applications) : gérer vos applications et leurs droits\n- [Contrôle d'accès](../dev/07-access-control-model) : comprendre les niveaux d'administration","anchor":"aller-plus-loin"},{"id":"v1.0-user-11-audit-logs-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"11-audit-logs","chapterTitle":"Journaux d'audit","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous devez **vérifier qu'une action a bien été effectuée** (ex. : un utilisateur a-t-il bien été désactivé ?)\n- Vous souhaitez **détecter des comportements suspects** (tentatives de connexion échoué","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-11-audit-logs-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"11-audit-logs","chapterTitle":"Journaux d'audit","heading":"Accéder aux journaux","snippet":"Depuis le menu principal à gauche, cliquez sur **Sécurité** puis **Journaux d'audit**.\n\nEn haut de la page, quatre indicateurs vous alertent en temps réel :\n\n- **Total des entrées** : volume global de","anchor":"accder-aux-journaux"},{"id":"v1.0-user-11-audit-logs-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"11-audit-logs","chapterTitle":"Journaux d'audit","heading":"Filtrer les journaux","snippet":"Utilisez les filtres en haut de la liste pour affiner votre recherche :\n\n- **Identifiant utilisateur** : pour voir toutes les actions d'une personne précise\n- **Niveau de sévérité** : Critique, Erreur","anchor":"filtrer-les-journaux"},{"id":"v1.0-user-11-audit-logs-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"11-audit-logs","chapterTitle":"Journaux d'audit","heading":"Vérifier l'intégrité des journaux","snippet":"Vous pouvez sélectionner plusieurs entrées de journal et cliquer sur **Vérifier** pour contrôler que ces entrées n'ont pas été altérées. Une icône verte confirme l'intégrité, une icône rouge indique u","anchor":"vrifier-lintgrit-des-journaux"},{"id":"v1.0-user-11-audit-logs-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"11-audit-logs","chapterTitle":"Journaux d'audit","heading":"Exporter les journaux","snippet":"1. Cliquez sur **Exporter** (ou appuyez sur **E**).\n2. Choisissez le format : tableau structuré ou fichier délimité.\n3. Définissez la plage de dates souhaitée.\n4. Saisissez la **raison de l'export** (","anchor":"exporter-les-journaux"},{"id":"v1.0-user-11-audit-logs-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"11-audit-logs","chapterTitle":"Journaux d'audit","heading":"Raccourcis clavier","snippet":"| Touche | Action |\n|--------|--------|\n| **R** | Rafraîchir la liste |\n| **F** | Ouvrir les filtres |\n| **E** | Exporter |\n| **Échap** | Fermer la fenêtre |\n| **J / K** | Naviguer entre les entrées |","anchor":"raccourcis-clavier"},{"id":"v1.0-user-11-audit-logs-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"11-audit-logs","chapterTitle":"Journaux d'audit","heading":"Aller plus loin","snippet":"- [Module HDS — conformité et rapports réglementaires](./hds)\n- [Module Stellar — preuves d'intégrité blockchain](./stellar)","anchor":"aller-plus-loin"},{"id":"v1.0-user-15-antivirus-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"15-antivirus","chapterTitle":"Module Antivirus","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **vérifier que le service antivirus est opérationnel**\n- Un fichier a été **placé en quarantaine** et vous devez décider de son sort\n- Vous voulez **consulter les scans en attente** o","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-15-antivirus-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"15-antivirus","chapterTitle":"Module Antivirus","heading":"Tableau de bord antivirus","snippet":"Depuis le menu principal à gauche, cliquez sur **Sécurité** puis **Antivirus**.\n\nLes indicateurs principaux s'affichent :\n\n- **Statut du service** : Opérationnel, Dégradé ou Hors ligne — un voyant col","anchor":"tableau-de-bord-antivirus"},{"id":"v1.0-user-15-antivirus-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"15-antivirus","chapterTitle":"Module Antivirus","heading":"Gérer la quarantaine","snippet":"Accédez à la section **Quarantaine** pour consulter les fichiers mis en attente. Pour chaque fichier, vous pouvez :\n- **Libérer** le fichier si vous l'identifiez comme sûr (faux positif)\n- **Supprimer","anchor":"grer-la-quarantaine"},{"id":"v1.0-user-15-antivirus-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"15-antivirus","chapterTitle":"Module Antivirus","heading":"Suivre la file d'attente des analyses","snippet":"La section **File d'attente** liste les fichiers en cours d'analyse ou en attente de traitement. Vous pouvez surveiller l'avancement des opérations et identifier d'éventuels blocages.","anchor":"suivre-la-file-dattente-des-analyses"},{"id":"v1.0-user-15-antivirus-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"15-antivirus","chapterTitle":"Module Antivirus","heading":"Configurer les politiques d'analyse","snippet":"La section **Politiques** vous permet de définir les règles d'analyse : quels types de fichiers analyser, quelle action appliquer automatiquement en cas de détection (mise en quarantaine, blocage, not","anchor":"configurer-les-politiques-danalyse"},{"id":"v1.0-user-15-antivirus-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"15-antivirus","chapterTitle":"Module Antivirus","heading":"Aller plus loin","snippet":"- [Journaux d'audit — tracer les événements de sécurité](./audit-logs)\n- [Module HDS — sécurité des données de santé](./hds)","anchor":"aller-plus-loin"},{"id":"v1.0-user-20-hds-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"20-hds","chapterTitle":"Module HDS","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **surveiller l'activité** sur les données de santé (connexions, accès aux coffres, modifications)\n- Vous devez **vérifier l'intégrité** des données stockées dans les coffres\n- Vous vo","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-20-hds-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"20-hds","chapterTitle":"Module HDS","heading":"Vue d'ensemble","snippet":"Depuis le menu principal, cliquez sur **Sécurité** puis **HDS**.\n\nLes indicateurs affichent en temps réel :\n\n- **Réseaux actifs** : le nombre de réseaux HDS opérationnels\n- **Coffres de données** : le","anchor":"vue-densemble"},{"id":"v1.0-user-20-hds-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"20-hds","chapterTitle":"Module HDS","heading":"Consulter les transactions","snippet":"La section **Transactions** liste tous les événements tracés sur les données de santé, classés par catégorie : authentification, accès aux coffres, manipulation de documents, modifications de permissi","anchor":"consulter-les-transactions"},{"id":"v1.0-user-20-hds-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"20-hds","chapterTitle":"Module HDS","heading":"Vérifier l'intégrité des données","snippet":"1. Accédez à **HDS** puis **Intégrité**.\n2. Sélectionnez le réseau à auditer dans le menu déroulant.\n3. Cliquez sur **Vérifier l'intégrité**.\n4. Le résultat s'affiche avec un badge **Valide** (vert) o","anchor":"vrifier-lintgrit-des-donnes"},{"id":"v1.0-user-20-hds-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"20-hds","chapterTitle":"Module HDS","heading":"Sécurité — Accès et incidents","snippet":"La section **Sécurité** affiche trois compteurs :\n\n- **Accès d'urgence** : nombre d'utilisations du mode \"break glass\" (accès exceptionnel à des données normalement restreintes)\n- **Échecs d'authentif","anchor":"scurit-accs-et-incidents"},{"id":"v1.0-user-20-hds-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"20-hds","chapterTitle":"Module HDS","heading":"Gérer les permissions HDS","snippet":"La section **Permissions** vous offre une vue d'ensemble des droits accordés à chaque utilisateur sur les différents réseaux HDS. Vous pouvez identifier rapidement qui a accès à quoi et ajuster si néc","anchor":"grer-les-permissions-hds"},{"id":"v1.0-user-20-hds-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"20-hds","chapterTitle":"Module HDS","heading":"Générer des rapports réglementaires","snippet":"1. Accédez à **HDS** puis **Conformité**.\n2. Choisissez le type de rapport : **Audit HDS**, **RGPD** ou **NIS2**.\n3. Cliquez sur **Générer**.\n\nLa génération peut prendre quelques instants. Le statut p","anchor":"gnrer-des-rapports-rglementaires"},{"id":"v1.0-user-20-hds-7","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"20-hds","chapterTitle":"Module HDS","heading":"Sauvegardes HDS","snippet":"La section **Sauvegardes** vous permet de déclencher ou de consulter les sauvegardes des données de santé. Un seul mécanisme de sauvegarde est disponible : un export de la base de données suivi d'un s","anchor":"sauvegardes-hds"},{"id":"v1.0-user-20-hds-8","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"20-hds","chapterTitle":"Module HDS","heading":"Aller plus loin","snippet":"- [Journaux d'audit](./audit-logs)\n- [Module Stellar — preuves d'intégrité blockchain](./stellar)\n- [Gérer les rôles HDS des utilisateurs](./users)","anchor":"aller-plus-loin"},{"id":"v1.0-user-16-stellar-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"16-stellar","chapterTitle":"Module Stellar (preuves blockchain)","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous devez **prouver à un auditeur externe** que vos journaux n'ont pas été falsifiés\n- Vous souhaitez **vérifier que les synchronisations** avec la blockchain se déroulent normalement\n- Vous voulez","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-16-stellar-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"16-stellar","chapterTitle":"Module Stellar (preuves blockchain)","heading":"Accéder aux preuves blockchain","snippet":"Depuis le menu principal à gauche, cliquez sur **Sécurité** puis **Stellar**.\n\nLes indicateurs en haut de la page vous donnent une vue rapide :\n\n- **Nombre de preuves enregistrées** : le total des emp","anchor":"accder-aux-preuves-blockchain"},{"id":"v1.0-user-16-stellar-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"16-stellar","chapterTitle":"Module Stellar (preuves blockchain)","heading":"Consulter le détail des preuves","snippet":"Le tableau liste toutes les preuves enregistrées. Vous pouvez filtrer par **réseau**, par **statut** (succès, en erreur, en attente) et par **période**.\n\nChaque ligne indique la date d'ancrage, le rés","anchor":"consulter-le-dtail-des-preuves"},{"id":"v1.0-user-16-stellar-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"16-stellar","chapterTitle":"Module Stellar (preuves blockchain)","heading":"Aller plus loin","snippet":"- [Consulter les journaux d'audit](./audit-logs)\n- [Module HDS — conformité et rapports réglementaires](./hds)","anchor":"aller-plus-loin"},{"id":"v1.0-user-12-credits-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"12-credits","chapterTitle":"Crédits","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous voulez **vérifier votre solde** disponible\n- Vous souhaitez **identifier les opérations les plus consommatrices**\n- Vous devez **justifier la consommation** dans le cadre d'un suivi budgétaire","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-12-credits-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"12-credits","chapterTitle":"Crédits","heading":"Accéder au suivi des crédits","snippet":"Depuis le menu principal à gauche, cliquez sur **Business** puis **Crédits**.\n\nTrois indicateurs clés s'affichent en haut de la page :\n\n- **Solde actuel** : le nombre de crédits encore disponibles (af","anchor":"accder-au-suivi-des-crdits"},{"id":"v1.0-user-12-credits-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"12-credits","chapterTitle":"Crédits","heading":"Analyser votre consommation","snippet":"Un graphique en barres vous permet de visualiser l'évolution de votre consommation sur trois périodes : par **jour**, par **semaine** ou par **mois**. Cliquez sur les onglets pour changer la période a","anchor":"analyser-votre-consommation"},{"id":"v1.0-user-12-credits-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"12-credits","chapterTitle":"Crédits","heading":"Aller plus loin","snippet":"- [Acheter des crédits](./billing)\n- [Configurer le coût des opérations](./pricing)","anchor":"aller-plus-loin"},{"id":"v1.0-user-13-billing-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"13-billing","chapterTitle":"Facturation","heading":"Quand utilisez-vous cette section ?","snippet":"- Votre solde de crédits est faible et vous devez **en acheter**\n- Vous souhaitez **choisir un pack adapté** à votre volume d'utilisation","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-13-billing-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"13-billing","chapterTitle":"Facturation","heading":"Acheter des crédits","snippet":"Depuis le menu principal à gauche, cliquez sur **Business** puis **Facturation**.\n\nQuatre packs sont proposés :\n\n| Pack | Crédits inclus | Prix | Avantage |\n|------|---------------|------|----------|\n","anchor":"acheter-des-crdits"},{"id":"v1.0-user-13-billing-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"13-billing","chapterTitle":"Facturation","heading":"Aller plus loin","snippet":"- [Suivre votre consommation de crédits](./credits)\n- [Configurer le coût des opérations](./pricing)","anchor":"aller-plus-loin"},{"id":"v1.0-user-17-projects-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"17-projects","chapterTitle":"Projets","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **créer un nouveau projet** et en suivre l'avancement\n- Vous devez **constituer l'équipe projet** et lui attribuer des rôles\n- Vous voulez **planifier les jalons** sur une frise chron","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-17-projects-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"17-projects","chapterTitle":"Projets","heading":"Accéder à la liste des projets","snippet":"Depuis le menu principal à gauche, cliquez sur **Projets**.\n\nLa liste affiche, pour chaque projet : son **nom**, son **statut** (Brouillon, Actif, Terminé, Archivé, Annulé), le **partenaire** propriét","anchor":"accder-la-liste-des-projets"},{"id":"v1.0-user-17-projects-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"17-projects","chapterTitle":"Projets","heading":"Créer un projet","snippet":"1. Cliquez sur **+ Nouveau projet**.\n2. Renseignez le nom, le statut initial et les informations générales.\n3. Cliquez sur **Créer**.","anchor":"crer-un-projet"},{"id":"v1.0-user-17-projects-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"17-projects","chapterTitle":"Projets","heading":"Gérer un projet existant","snippet":"Cliquez sur le nom du projet pour accéder à sa vue principale. Plusieurs sections sont disponibles :\n\n- **Édition** : modifier les informations générales du projet\n- **Équipe** : ajouter des membres e","anchor":"grer-un-projet-existant"},{"id":"v1.0-user-17-projects-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"17-projects","chapterTitle":"Projets","heading":"Rédiger des spécifications avec l'assistant IA","snippet":"WakaStart intègre un éditeur de spécifications assisté par intelligence artificielle. Accédez-y depuis **Projets** puis **Spécifications**.\n\nL'assistant vous aide à rédiger, structurer et compléter vo","anchor":"rdiger-des-spcifications-avec-lassistant-ia"},{"id":"v1.0-user-17-projects-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"17-projects","chapterTitle":"Projets","heading":"Aller plus loin","snippet":"- [Gérer les partenaires](./partners)\n- [Consulter les journaux d'audit d'un projet](./audit-logs)","anchor":"aller-plus-loin"},{"id":"v1.0-user-21-prospects-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"21-prospects","chapterTitle":"Prospects et gestion commerciale","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous voulez **suivre vos opportunités commerciales** et leur état d'avancement\n- Vous souhaitez **créer un devis** pour un nouveau prospect\n- Vous devez **estimer le coût** d'un projet WakaStart ava","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-21-prospects-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"21-prospects","chapterTitle":"Prospects et gestion commerciale","heading":"Tableau de bord commercial","snippet":"Depuis le menu principal à gauche, cliquez sur **Business** puis **Prospects**.\n\nLe tableau de bord affiche :\n\n- **Nombre total de devis** et leur répartition par statut : Créé, Envoyé, Refusé, Signé\n","anchor":"tableau-de-bord-commercial"},{"id":"v1.0-user-21-prospects-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"21-prospects","chapterTitle":"Prospects et gestion commerciale","heading":"Gérer vos projets commerciaux","snippet":"Accédez à la section **Commercial** pour consulter et gérer vos dossiers prospects. Chaque dossier a un statut : Brouillon, Actif, À relancer, Abandonné, Perdu ou Gagné.","anchor":"grer-vos-projets-commerciaux"},{"id":"v1.0-user-21-prospects-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"21-prospects","chapterTitle":"Prospects et gestion commerciale","heading":"Créer un devis avec l'estimateur","snippet":"Accédez à **Prospects** puis **Devis** pour utiliser l'estimateur de prix WakaStart. Il vous permet de construire une offre en sélectionnant les éléments suivants :\n\n- **Pack de démarrage** : Simple, ","anchor":"crer-un-devis-avec-lestimateur"},{"id":"v1.0-user-21-prospects-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"21-prospects","chapterTitle":"Prospects et gestion commerciale","heading":"Estimateur TopFlix Academy","snippet":"Un estimateur dédié est disponible pour l'offre **TopFlix Academy** :\n\n| Formule | Prix mensuel | Inclus |\n|---------|-------------|--------|\n| **Basic** | 100 €/mois | 10 utilisateurs, 3 catégories, ","anchor":"estimateur-topflix-academy"},{"id":"v1.0-user-21-prospects-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"21-prospects","chapterTitle":"Prospects et gestion commerciale","heading":"Aller plus loin","snippet":"- [Gestion des projets](./projects)\n- [Facturation et crédits](./billing)","anchor":"aller-plus-loin"},{"id":"v1.0-user-22-entities-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"22-entities","chapterTitle":"Entités juridiques et contacts","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous devez **enregistrer les informations légales** d'une nouvelle organisation (SIRET, RCS, adresse...)\n- Vous souhaitez **ajouter ou modifier un contact** dans une organisation\n- Vous voulez **con","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-22-entities-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"22-entities","chapterTitle":"Entités juridiques et contacts","heading":"Accéder aux entités et contacts","snippet":"Depuis le menu principal à gauche, cliquez sur **Business** puis **Entités**.\n\nDeux onglets sont disponibles : **Entités** et **Contacts**.","anchor":"accder-aux-entits-et-contacts"},{"id":"v1.0-user-22-entities-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"22-entities","chapterTitle":"Entités juridiques et contacts","heading":"Gérer les entités juridiques","snippet":"Chaque entité regroupe les informations légales et administratives d'une organisation :\n\n- **Nom commercial** et **Raison sociale**\n- **Forme juridique** (SAS, SARL, Association...)\n- **Numéro SIRET**","anchor":"grer-les-entits-juridiques"},{"id":"v1.0-user-22-entities-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"22-entities","chapterTitle":"Entités juridiques et contacts","heading":"Gérer les contacts","snippet":"Chaque contact est rattaché à une entité juridique et représente un interlocuteur humain :\n\n- **Civilité**, **Prénom**, **Nom**\n- **Fonction** dans l'organisation\n- **Adresse e-mail professionnelle**\n","anchor":"grer-les-contacts"},{"id":"v1.0-user-22-entities-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"22-entities","chapterTitle":"Entités juridiques et contacts","heading":"Aller plus loin","snippet":"- [Créer un partenaire](./partners)\n- [Créer un client](./customers)","anchor":"aller-plus-loin"},{"id":"v1.0-user-25-pricing-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"25-pricing","chapterTitle":"Module Tarification (Pricing)","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **consulter le coût** de chaque action disponible sur la plateforme\n- Vous devez **modifier le tarif** d'une action (accès réservé aux administrateurs de niveau élevé)\n- Vous voulez *","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-25-pricing-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"25-pricing","chapterTitle":"Module Tarification (Pricing)","heading":"Accéder à la tarification","snippet":"Depuis le menu principal à gauche, cliquez sur **Business** puis **Tarification**.\n\nL'écran est divisé en deux colonnes :\n\n- **À gauche** : la liste des modules (groupes d'actions)\n- **À droite** : le","anchor":"accder-la-tarification"},{"id":"v1.0-user-25-pricing-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"25-pricing","chapterTitle":"Module Tarification (Pricing)","heading":"Consulter et modifier les tarifs","snippet":"Cliquez sur un module dans la liste de gauche pour afficher ses actions et leurs tarifs correspondants en crédits.\n\nPour chaque action, vous pouvez consulter :\n\n- **Tarif standard** : le coût par défa","anchor":"consulter-et-modifier-les-tarifs"},{"id":"v1.0-user-25-pricing-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"25-pricing","chapterTitle":"Module Tarification (Pricing)","heading":"Aller plus loin","snippet":"- [Suivre la consommation de crédits](./credits)\n- [Acheter des crédits](./billing)","anchor":"aller-plus-loin"},{"id":"v1.0-user-14-media-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"14-media","chapterTitle":"Médias","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **consulter ou administrer** les fichiers médias de la plateforme\n- Vous devez **configurer le service de gestion des médias**\n- Vous voulez **suivre l'état des traitements** en cours","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-14-media-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"14-media","chapterTitle":"Médias","heading":"Accéder à la gestion des médias","snippet":"Depuis le menu principal à gauche, cliquez sur **Médias**.\n\nDeux sous-sections sont disponibles :","anchor":"accder-la-gestion-des-mdias"},{"id":"v1.0-user-14-media-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"14-media","chapterTitle":"Médias","heading":"Configuration du service médias","snippet":"Accédez aux paramètres de configuration du service : formats supportés, taille maximale des fichiers, options de traitement automatique.","anchor":"configuration-du-service-mdias"},{"id":"v1.0-user-14-media-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"14-media","chapterTitle":"Médias","heading":"Traitements en cours et terminés","snippet":"Consultez la liste des opérations de traitement (conversion, redimensionnement, analyse antivirus...) avec leur statut : en attente, en cours ou terminé. Les erreurs éventuelles sont signalées clairem","anchor":"traitements-en-cours-et-termins"},{"id":"v1.0-user-14-media-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"14-media","chapterTitle":"Médias","heading":"Aller plus loin","snippet":"- [Module Antivirus — analyse des fichiers](./antivirus)\n- [Sauvegarde et restauration](./backup)","anchor":"aller-plus-loin"},{"id":"v1.0-user-18-settings-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"18-settings","chapterTitle":"Paramètres","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **changer le thème d'affichage** de l'interface\n- Vous devez **connecter un compte cloud** (OVH, AWS, GCP...) à la plateforme\n- Vous voulez **activer ou désactiver des fonctionnalités","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-18-settings-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"18-settings","chapterTitle":"Paramètres","heading":"Apparence","snippet":"Depuis le menu principal, cliquez sur **Paramètres**.\n\nChoisissez votre mode d'affichage parmi trois options :\n\n- **Clair** : thème lumineux, idéal en plein jour\n- **Sombre** : réduit la fatigue ocula","anchor":"apparence"},{"id":"v1.0-user-18-settings-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"18-settings","chapterTitle":"Paramètres","heading":"Comptes cloud","snippet":"Accédez à **Paramètres** puis **Cloud Providers** pour connecter et gérer vos comptes auprès de fournisseurs d'infrastructure (OVH, Amazon Web Services, Google Cloud Platform, etc.). Ces connexions so","anchor":"comptes-cloud"},{"id":"v1.0-user-18-settings-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"18-settings","chapterTitle":"Paramètres","heading":"Fonctionnalités des réseaux","snippet":"Accédez à **Paramètres** puis **Fonctionnalités Réseaux** pour activer ou désactiver des fonctionnalités avancées disponibles à l'échelle de vos réseaux.","anchor":"fonctionnalits-des-rseaux"},{"id":"v1.0-user-18-settings-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"18-settings","chapterTitle":"Paramètres","heading":"Fonctionnalités des clients","snippet":"Accédez à **Paramètres** puis **Fonctionnalités Clients** pour activer ou désactiver des fonctionnalités avancées disponibles pour les organisations clientes.","anchor":"fonctionnalits-des-clients"},{"id":"v1.0-user-18-settings-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"18-settings","chapterTitle":"Paramètres","heading":"Aller plus loin","snippet":"- [Mon profil — préférences personnelles](./profile)\n- [Gestion des réseaux](./networks)\n- [Gestion des clients](./customers)","anchor":"aller-plus-loin"},{"id":"v1.0-user-23-identity-providers-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"23-identity-providers","chapterTitle":"Fournisseurs d'identité (SSO)","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **permettre à vos utilisateurs de se connecter avec leurs comptes d'entreprise** (Google, Microsoft, Okta...)\n- Vous devez **activer ou désactiver** une connexion SSO existante\n- Vous","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-23-identity-providers-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"23-identity-providers","chapterTitle":"Fournisseurs d'identité (SSO)","heading":"Accéder aux fournisseurs d'identité","snippet":"Depuis le menu principal à gauche, cliquez sur **Personnalisation** puis **Fournisseurs d'identité**.\n\nLa liste affiche les connexions SSO configurées pour votre organisation, avec leur statut (actif ","anchor":"accder-aux-fournisseurs-didentit"},{"id":"v1.0-user-23-identity-providers-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"23-identity-providers","chapterTitle":"Fournisseurs d'identité (SSO)","heading":"Configurer une connexion SSO","snippet":"","anchor":"configurer-une-connexion-sso"},{"id":"v1.0-user-23-identity-providers-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"23-identity-providers","chapterTitle":"Fournisseurs d'identité (SSO)","heading":"Fournisseurs pré-configurés","snippet":"Pour les fournisseurs courants, la configuration est simplifiée. Cliquez sur **+ Ajouter un fournisseur** et sélectionnez :\n\n- **Google** : connexion via compte Google Workspace\n- **Microsoft** : conn","anchor":"fournisseurs-pr-configurs"},{"id":"v1.0-user-23-identity-providers-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"23-identity-providers","chapterTitle":"Fournisseurs d'identité (SSO)","heading":"Configuration SAML 2.0","snippet":"Pour les fournisseurs d'identité d'entreprise qui utilisent le standard SAML 2.0 (Okta, Ping Identity, ADFS...) :\n\n1. Sélectionnez le type **SAML 2.0**.\n2. Renseignez les informations fournies par vot","anchor":"configuration-saml-20"},{"id":"v1.0-user-23-identity-providers-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"23-identity-providers","chapterTitle":"Fournisseurs d'identité (SSO)","heading":"Configuration OpenID Connect","snippet":"Pour les fournisseurs compatibles OpenID Connect, sélectionnez le type **OpenID Connect** et suivez les étapes guidées.","anchor":"configuration-openid-connect"},{"id":"v1.0-user-23-identity-providers-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"23-identity-providers","chapterTitle":"Fournisseurs d'identité (SSO)","heading":"Gérer une connexion existante","snippet":"Pour chaque fournisseur configuré, vous disposez des actions suivantes :\n\n- **Activer / Désactiver** : contrôle immédiat de la connexion\n- **Synchroniser** : force une mise à jour depuis l'annuaire ex","anchor":"grer-une-connexion-existante"},{"id":"v1.0-user-23-identity-providers-7","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"23-identity-providers","chapterTitle":"Fournisseurs d'identité (SSO)","heading":"Aller plus loin","snippet":"- [Gérer les utilisateurs](./users)\n- [Paramètres de l'organisation](./settings)","anchor":"aller-plus-loin"},{"id":"v1.0-user-24-backup-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"24-backup","chapterTitle":"Sauvegarde et restauration","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **créer une copie de sauvegarde** de la configuration d'une application\n- Vous voulez **dupliquer une application** ou un réseau existant pour en créer une variante\n- Vous devez **res","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-24-backup-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"24-backup","chapterTitle":"Sauvegarde et restauration","heading":"Exporter une configuration","snippet":"Depuis le menu principal à gauche, cliquez sur **Administration** puis **Sauvegarde**.\n\nTrois sections vous permettent d'exporter séparément les configurations de vos **Applications**, **Réseaux** et ","anchor":"exporter-une-configuration"},{"id":"v1.0-user-24-backup-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"24-backup","chapterTitle":"Sauvegarde et restauration","heading":"Importer une configuration","snippet":"L'import se déroule en quatre étapes guidées :\n\n1. **Déposer le fichier** : glissez-déposez votre fichier de sauvegarde dans la zone prévue, ou cliquez pour le sélectionner.\n2. **Analyse automatique**","anchor":"importer-une-configuration"},{"id":"v1.0-user-24-backup-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"24-backup","chapterTitle":"Sauvegarde et restauration","heading":"Aller plus loin","snippet":"- [Gestion des applications](./applications)\n- [Gestion des réseaux](./networks)\n- [Gestion des clients](./customers)","anchor":"aller-plus-loin"},{"id":"v1.0-user-26-wakaadmin-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"26-wakaadmin","chapterTitle":"Administration plateforme (WakaAdmin)","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous devez **gérer les noms de domaine** utilisés pour héberger des applications\n- Vous souhaitez **configurer les points d'entrée réseau** (routage du trafic)\n- Vous devez **gérer le registre d'ima","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-26-wakaadmin-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"26-wakaadmin","chapterTitle":"Administration plateforme (WakaAdmin)","heading":"Domaines","snippet":"Gérez les noms de domaine racines utilisés pour héberger les applications de la plateforme. Les fournisseurs DNS supportés sont OVH et Cloudflare. Depuis cette section, vous pouvez créer, modifier ou ","anchor":"domaines"},{"id":"v1.0-user-26-wakaadmin-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"26-wakaadmin","chapterTitle":"Administration plateforme (WakaAdmin)","heading":"Passerelles réseau (Gateways)","snippet":"Les passerelles sont les points d'entrée du trafic web vers les applications hébergées. Gérez ici la liste des passerelles et leur configuration de routage.","anchor":"passerelles-rseau-gateways"},{"id":"v1.0-user-26-wakaadmin-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"26-wakaadmin","chapterTitle":"Administration plateforme (WakaAdmin)","heading":"Registre d'images Harbor","snippet":"Harbor est le registre qui stocke et distribue les images de vos applications (comparable à un entrepôt d'emballages prêts à déployer). Cinq sous-sections sont disponibles :\n\n- **Instances** : les ser","anchor":"registre-dimages-harbor"},{"id":"v1.0-user-26-wakaadmin-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"26-wakaadmin","chapterTitle":"Administration plateforme (WakaAdmin)","heading":"Coffre de secrets (OpenBao)","snippet":"OpenBao est le coffre-fort numérique de la plateforme — il stocke de façon ultra-sécurisée les identifiants, clés et certificats nécessaires au fonctionnement des services. Trois types de coffres sont","anchor":"coffre-de-secrets-openbao"},{"id":"v1.0-user-26-wakaadmin-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"26-wakaadmin","chapterTitle":"Administration plateforme (WakaAdmin)","heading":"Dépôts de code","snippet":"Gérez les dépôts de code source rattachés à la plateforme pour les applications déployées via WakaStart.","anchor":"dpts-de-code"},{"id":"v1.0-user-26-wakaadmin-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"26-wakaadmin","chapterTitle":"Administration plateforme (WakaAdmin)","heading":"Fournisseurs SMTP","snippet":"Configurez les serveurs d'envoi d'e-mails utilisés pour les notifications, invitations et communications automatiques de la plateforme. Un bouton **Tester** permet de vérifier qu'un serveur SMTP répon","anchor":"fournisseurs-smtp"},{"id":"v1.0-user-26-wakaadmin-7","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"26-wakaadmin","chapterTitle":"Administration plateforme (WakaAdmin)","heading":"Variables de plateforme","snippet":"Définissez les variables de configuration globales accessibles par l'ensemble des composants de la plateforme. Ces variables permettent de centraliser des paramètres partagés sans avoir à les saisir m","anchor":"variables-de-plateforme"},{"id":"v1.0-user-26-wakaadmin-8","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"26-wakaadmin","chapterTitle":"Administration plateforme (WakaAdmin)","heading":"Monitoring","snippet":"Configurez des moniteurs de disponibilité pour vos applications et services : WakaStart envoie régulièrement une requête de vérification (\"ping\") vers l'adresse surveillée et vous alerte si elle ne ré","anchor":"monitoring"},{"id":"v1.0-user-26-wakaadmin-9","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"26-wakaadmin","chapterTitle":"Administration plateforme (WakaAdmin)","heading":"Observabilité","snippet":"Accédez aux outils avancés de supervision de la plateforme : métriques de performance, traces d'exécution et journaux système consolidés. Cette vue est destinée aux administrateurs techniques pour dia","anchor":"observabilit"},{"id":"v1.0-user-26-wakaadmin-10","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"26-wakaadmin","chapterTitle":"Administration plateforme (WakaAdmin)","heading":"Aller plus loin","snippet":"- [Gestion des applications](./applications)\n- [Journaux d'audit](./audit-logs)\n- [Sauvegarde et restauration](./backup)","anchor":"aller-plus-loin"},{"id":"v1.0-user-19-profile-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"19-profile","chapterTitle":"Mon profil","heading":"Quand utilisez-vous cette section ?","snippet":"- Vous souhaitez **mettre à jour vos coordonnées** (téléphone, fonction)\n- Vous voulez **changer votre langue d'interface** ou votre **fuseau horaire**\n- Vous souhaitez **vérifier quels droits vous av","anchor":"quand-utilisez-vous-cette-section-"},{"id":"v1.0-user-19-profile-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"19-profile","chapterTitle":"Mon profil","heading":"Accéder à votre profil","snippet":"Cliquez sur votre **avatar** en haut à droite de l'écran, puis sélectionnez **Mon profil**.","anchor":"accder-votre-profil"},{"id":"v1.0-user-19-profile-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"19-profile","chapterTitle":"Mon profil","heading":"Informations que vous pouvez modifier","snippet":"- **Prénom** et **Nom**\n- **Fonction** : votre intitulé de poste\n- **Téléphone fixe** et **Téléphone mobile**\n- **Fuseau horaire** : pour que les dates et heures s'affichent dans votre référentiel\n- *","anchor":"informations-que-vous-pouvez-modifier"},{"id":"v1.0-user-19-profile-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"19-profile","chapterTitle":"Mon profil","heading":"Informations en lecture seule","snippet":"Certaines informations sont gérées par votre administrateur et ne peuvent pas être modifiées depuis votre profil :\n\n- **Adresse e-mail** : votre identifiant de connexion\n- **Identifiant Wakastellar** ","anchor":"informations-en-lecture-seule"},{"id":"v1.0-user-19-profile-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"19-profile","chapterTitle":"Mon profil","heading":"Aller plus loin","snippet":"- [Paramètres généraux de l'interface](./settings)","anchor":"aller-plus-loin"},{"id":"v1.0-user-99-glossary-0","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Partenaire","snippet":"Société ou entité qui distribue ou opère des applications via WakaStart. Le Partenaire est au sommet de la hiérarchie organisationnelle : Partenaire → Réseau → Client → Utilisateur.","anchor":"partenaire"},{"id":"v1.0-user-99-glossary-1","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Réseau","snippet":"Groupement de Clients sous une même organisation logique. Un Réseau est rattaché à une Application et hérite de ses paramètres de base (langue, thème...).","anchor":"rseau"},{"id":"v1.0-user-99-glossary-2","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Client","snippet":"Organisation (entreprise, association, service public...) à qui vous donnez accès à votre plateforme. Les utilisateurs finaux se connectent dans le contexte d'un Client.","anchor":"client"},{"id":"v1.0-user-99-glossary-3","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Application","snippet":"Service ou produit numérique hébergé et distribué via WakaStart. Elle est rattachée à un Partenaire et peut être déployée pour plusieurs Réseaux et Clients.","anchor":"application"},{"id":"v1.0-user-99-glossary-4","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Profil","snippet":"Ensemble de droits regroupés sous un nom (ex. : \"Responsable facturation\"). On attribue un ou plusieurs Profils à un utilisateur pour lui donner accès aux fonctionnalités correspondantes.","anchor":"profil"},{"id":"v1.0-user-99-glossary-5","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Équipe","snippet":"Groupe d'utilisateurs au sein d'un même Client, avec un niveau d'accès collectif. Utile pour organiser les accès par service ou fonction.","anchor":"quipe"},{"id":"v1.0-user-99-glossary-6","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Clé API","snippet":"Identifiant sécurisé permettant à un outil externe d'interagir avec WakaStart sans passer par l'interface web. Associée à un utilisateur et à une application.","anchor":"cl-api"},{"id":"v1.0-user-99-glossary-7","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Niveaux d'administration","snippet":"Les rôles qui définissent ce qu'un utilisateur peut faire sur la plateforme :\n\n| Niveau | Ce qu'il permet |\n|--------|----------------|\n| **WakaAdmin** | Accès complet à toute la plateforme et à l'inf","anchor":"niveaux-dadministration"},{"id":"v1.0-user-99-glossary-8","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Droits applicatifs","snippet":"Permissions fines accordées via les Profils :\n\n| Droit | Ce qu'il permet |\n|-------|----------------|\n| **Facturation** | Accéder à la section facturation et crédits |\n| **Configuration** | Accéder au","anchor":"droits-applicatifs"},{"id":"v1.0-user-99-glossary-9","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Niveaux d'équipe","snippet":"Au sein d'une Équipe, chaque membre a un niveau : Admin, Manager, Membre, Contributeur, Lecteur, ou Aucun.","anchor":"niveaux-dquipe"},{"id":"v1.0-user-99-glossary-10","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Rôles HDS","snippet":"Rôles spécifiques au contexte des données de santé, attribués aux utilisateurs qui ont besoin d'accéder aux fonctionnalités HDS : Administrateur HDS, Patient, Professionnel de santé, Stockage HDS, Sup","anchor":"rles-hds"},{"id":"v1.0-user-99-glossary-11","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Statuts courants","snippet":"Les éléments de la plateforme (Partenaires, Réseaux, Clients, Applications...) ont un statut parmi : **Actif**, **Inactif**, **Suspendu**, **Supprimé**, **Brouillon**.","anchor":"statuts-courants"},{"id":"v1.0-user-99-glossary-12","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Filtre global","snippet":"La barre de navigation contextuelle présente en haut de chaque page. Elle permet de restreindre l'affichage à un Partenaire, un Réseau et/ou un Client spécifique.","anchor":"filtre-global"},{"id":"v1.0-user-99-glossary-13","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Blueprint (fichier de sauvegarde)","snippet":"Fichier décrivant la configuration complète d'une application. Peut être exporté depuis WakaStart et réimporté pour dupliquer ou restaurer un environnement.","anchor":"blueprint-fichier-de-sauvegarde"},{"id":"v1.0-user-99-glossary-14","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Stellar","snippet":"Blockchain publique et décentralisée utilisée par WakaStart pour ancrer des empreintes numériques de vos journaux d'audit, garantissant qu'ils ne peuvent pas être falsifiés après coup.","anchor":"stellar"},{"id":"v1.0-user-99-glossary-15","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Harbor","snippet":"Registre d'images d'applications utilisé par WakaStart pour stocker et distribuer les packages déployables. Comparable à un entrepôt d'emballages prêts à l'emploi pour chaque application.","anchor":"harbor"},{"id":"v1.0-user-99-glossary-16","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"OpenBao","snippet":"Coffre-fort numérique de la plateforme qui conserve de façon ultra-sécurisée les identifiants, clés et certificats nécessaires au fonctionnement des services.","anchor":"openbao"},{"id":"v1.0-user-99-glossary-17","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"Crédits","snippet":"Monnaie interne de WakaStart. Chaque action sur la plateforme (envoi d'e-mail, traitement de fichier, génération de document...) consomme un certain nombre de crédits.","anchor":"crdits"},{"id":"v1.0-user-99-glossary-18","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"HDS (Hébergement de Données de Santé)","snippet":"Certification française encadrant le stockage et le traitement de données de santé à caractère personnel. WakaStart propose un module dédié pour les organisations soumises à cette réglementation.","anchor":"hds-hbergement-de-donnes-de-sant"},{"id":"v1.0-user-99-glossary-19","version":"v1.0","sectionId":"user","sectionLabel":"Utilisateur","chapterId":"99-glossary","chapterTitle":"Glossaire","heading":"SSO (Single Sign-On)","snippet":"Connexion unique : mécanisme permettant à un utilisateur de se connecter à WakaStart avec ses identifiants d'entreprise existants (Google Workspace, Microsoft 365, Okta...).","anchor":"sso-single-sign-on"},{"id":"v1.0-dev-01-architecture-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Pourquoi cette étape","snippet":"Avant d'écrire la moindre ligne de code d'intégration, il faut comprendre comment les entités s'emboîtent et quels services exposent quelles frontières. Une erreur courante est de traiter la plateform","anchor":"pourquoi-cette-tape"},{"id":"v1.0-dev-01-architecture-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Hiérarchie multi-tenant","snippet":"WakaStart organise les entités de haut en bas :\n\n```\nPartner\n └── App ←── la Wakapp se connecte ici\n └── Network (1 realm Keycloak)\n └── Customer\n ├── User\n ","anchor":"hirarchie-multi-tenant"},{"id":"v1.0-dev-01-architecture-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Position de la WakaApp dans l'écosystème","snippet":"```\n ┌──────────────────────────────────────────┐\n │ PLATEFORME WAKASTART │\n │ │\n ┌──────────","anchor":"position-de-la-wakaapp-dans-lcosystme"},{"id":"v1.0-dev-01-architecture-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Les deux APIs publiques consommées par une Wakapp","snippet":"| API | Quand | Exemples d'endpoints |\n|-----|-------|----------------------|\n| **API Discovery** | **Avant** l'authentification | `POST /discover/start-login`, `GET /discover/subdomain`, `GET /discov","anchor":"les-deux-apis-publiques-consommes-par-une-wakapp"},{"id":"v1.0-dev-01-architecture-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Stack côté Wakastart vs côté WakaApp","snippet":"| Aspect | Plateforme WakaStart | Votre WakaApp |\n|--------|---------------------|---------------|\n| Auth | Keycloak OAuth2 PKCE | Implémenter le flow PKCE (voir chapitre 3) |\n| Token enrichi | Géré p","anchor":"stack-ct-wakastart-vs-ct-wakaapp"},{"id":"v1.0-dev-01-architecture-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Deux modes d'accès","snippet":"| Mode | Usage | Header(s) requis |\n|------|-------|-----------------|\n| **JWT Bearer + enriched** | Apps utilisateur (frontend proxifié) | `Authorization: Bearer ` + `x-enriched-token","anchor":"deux-modes-daccs"},{"id":"v1.0-dev-01-architecture-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Flux de communication (vue d'ensemble)","snippet":"```\n1. [PREAAUTH] Wakapp → API Discovery : POST /discover/start-login\n → URL Keycloak retournée\n Wakapp → Keycloak : redirect navigateur","anchor":"flux-de-communication-vue-densemble"},{"id":"v1.0-dev-01-architecture-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Bonnes pratiques","snippet":"- Stocker les tokens dans des **cookies HttpOnly** (jamais localStorage).\n- Utiliser les **WIDs** dans vos URLs et logs — les UUIDs sont internes.\n- Ne jamais inspecter ni vérifier la signature du `x-","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-01-architecture-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Aller plus loin","snippet":"- [Discovery — Identifier l'utilisateur](02-discovery) : premier appel avant auth\n- [Authentification — OAuth2 PKCE](03-authentication-overview) : flow complet\n- [Utilisation de l'API](10-api-conventi","anchor":"aller-plus-loin"},{"id":"v1.0-dev-02-discovery-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Pourquoi cette étape","snippet":"Avant toute authentification OAuth2, votre Wakapp doit savoir **vers quel realm Keycloak** rediriger l'utilisateur. Dans une architecture multi-tenant, chaque Network a son propre realm. Discovery rés","anchor":"pourquoi-cette-tape"},{"id":"v1.0-dev-02-discovery-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Concepts clés","snippet":"- **Subdomain** : chaîne courte identifiant un Network ou Customer (`app.test`, `acme-prod`). Peut contenir des points.\n- **WID** : identifiant court (6 chars alphanum) utilisé pour les entités (`NET0","anchor":"concepts-cls"},{"id":"v1.0-dev-02-discovery-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Les 3 patterns disponibles","snippet":"","anchor":"les-3-patterns-disponibles"},{"id":"v1.0-dev-02-discovery-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Pattern 1 — `start-login` par hostname (recommandé)","snippet":"Le flow recommandé pour les Wakapps mono-tenant. Discovery résout automatiquement le `client_id` Keycloak à partir du hostname.\n\n```http\nPOST {DISCOVERY_API_URL}/discover/start-login\nContent-Type: app","anchor":"pattern-1-start-login-par-hostname-recommand"},{"id":"v1.0-dev-02-discovery-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Pattern 2 — `start-login` par email (Microsoft-style)","snippet":"L'utilisateur saisit son email. Discovery identifie son organisation et retourne la même `keycloakUrl`.\n\n```http\nPOST {DISCOVERY_API_URL}/discover/start-login\nContent-Type: application/json\n\n{\n \"emai","anchor":"pattern-2-start-login-par-email-microsoft-style"},{"id":"v1.0-dev-02-discovery-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Pattern 3 — Lookup direct (informationnel)","snippet":"Pour afficher des infos avant le login (logo, nom de l'organisation, IDP type) ou après login pour le catalogue d'apps.\n\n```http\nGET /discover/email?email=john@acme.com\n```\n\n```json\n{\n \"users\": [{\n ","anchor":"pattern-3-lookup-direct-informationnel"},{"id":"v1.0-dev-02-discovery-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Lookup par subdomain","snippet":"```http\nGET /discover/subdomain?subdomain=acme-prod\n```\n\n```json\n{\n \"subdomain\": \"acme-prod\",\n \"result\": {\n \"type\": \"network\",\n \"network_wid\": \"NET001\",\n \"network_subdomain\": \"acme-prod\",\n ","anchor":"lookup-par-subdomain"},{"id":"v1.0-dev-02-discovery-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Lookup d'applications","snippet":"```http\nGET /discover/apps/customer?customerId={uuid_or_wid}\nGET /discover/apps/user?userId={uuid}\nGET /discover/apps/network?networkId={uuid}\n```\n\nRetourne les applications accessibles pour une entit","anchor":"lookup-dapplications"},{"id":"v1.0-dev-02-discovery-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Extraction du subdomain","snippet":"Le subdomain peut être **multi-label** (contient des points). Convention de nommage :\n\n```\n{subdomain}.{platform-domain}\n app.test.wakastart.app\n └──┬───┘ └──────┬─────┘\n subdomain platform","anchor":"extraction-du-subdomain"},{"id":"v1.0-dev-02-discovery-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Subdomain vs email — quand utiliser quoi","snippet":"| Critère | `host` (hostname) | `email` |\n|---------|-------------------|---------|\n| Wakapp mono-tenant | Recommandé | Non nécessaire |\n| Portail multi-tenant | Non adapté | Recommandé |\n| L'utilisat","anchor":"subdomain-vs-email-quand-utiliser-quoi"},{"id":"v1.0-dev-02-discovery-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Anti-énumération et throttling","snippet":"> [!WARNING]\n> L'anti-énumération n'est **pas** uniforme sur tout le service. `POST /discover/start-login` et les routes `/internal/*` normalisent la latence des réponses négatives. `GET /discover/ema","anchor":"anti-numration-et-throttling"},{"id":"v1.0-dev-02-discovery-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Gestion d'erreurs","snippet":"| Status | Body | Cause | Action |\n|--------|------|-------|--------|\n| `400` | `invalid_request` | `email` + `host` fournis simultanément, ou aucun | Vérifier le body |\n| `400` | `invalid_request` | ","anchor":"gestion-derreurs"},{"id":"v1.0-dev-02-discovery-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Bonnes pratiques","snippet":"- Appelez `start-login` une seule fois par tentative de login — ne retentez pas automatiquement sur `404`.\n- Extrayez le subdomain depuis `window.location.hostname` avec la fonction `extractSubdomain`","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-02-discovery-13","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Pièges classiques","snippet":"- **Mauvaise extraction du subdomain** : envoyer `host=\"app\"` au lieu de `host=\"app.test\"` → `404 not_found`. Voir la fonction `extractSubdomain` ci-dessus.\n- **`appId` hardcodé** : ne pas envoyer `ap","anchor":"piges-classiques"},{"id":"v1.0-dev-02-discovery-14","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"02-discovery","chapterTitle":"Discovery — Identifier l'utilisateur","heading":"Aller plus loin","snippet":"- [Authentification — OAuth2 PKCE](03-authentication-overview) : utiliser la `keycloakUrl` retournée par `start-login`\n- [Pièges classiques](17-pitfalls) : diagnostic des erreurs fréquentes de Discove","anchor":"aller-plus-loin"},{"id":"v1.0-dev-03-authentication-overview-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"03-authentication-overview","chapterTitle":"Authentification — Concepts & Flow","heading":"Pourquoi cette étape","snippet":"L'authentification est le flux le plus critique de votre intégration. Un flux mal implémenté expose à des vulnérabilités (code interception, CSRF, token leakage). Le PKCE (`Proof Key for Code Exchange","anchor":"pourquoi-cette-tape"},{"id":"v1.0-dev-03-authentication-overview-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"03-authentication-overview","chapterTitle":"Authentification — Concepts & Flow","heading":"Concepts clés","snippet":"- **code_verifier** : chaîne aléatoire 43-128 chars, générée côté client, stockée en sessionStorage.\n- **code_challenge** : `BASE64URL(SHA256(code_verifier))`, envoyé à Keycloak.\n- **access_token** : ","anchor":"concepts-cls"},{"id":"v1.0-dev-03-authentication-overview-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"03-authentication-overview","chapterTitle":"Authentification — Concepts & Flow","heading":"Flow complet en 10 étapes","snippet":"```mermaid\nsequenceDiagram\n participant F as Wakapp Frontend\n participant B as Wakapp Backend\n participant D as Discovery\n participant K as Keycloak\n participant BFF as BFF (enrich)\n\n F->>F: Gén","anchor":"flow-complet-en-10-tapes"},{"id":"v1.0-dev-03-authentication-overview-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"03-authentication-overview","chapterTitle":"Authentification — Concepts & Flow","heading":"Pré-requis Keycloak — Client OIDC","snippet":"Pour que le flow fonctionne, le client OIDC doit être configuré ainsi :\n\n| Paramètre | Valeur | Raison |\n|-----------|--------|--------|\n| **Client ID** | Valeur de `apps.client_id` en DB (auto-généré","anchor":"pr-requis-keycloak-client-oidc"},{"id":"v1.0-dev-03-authentication-overview-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"03-authentication-overview","chapterTitle":"Authentification — Concepts & Flow","heading":"Organizations Keycloak (IAM-C4 — obligatoire)","snippet":"le service d'authentification WakaStart rejette tout token Keycloak sans le claim `organization`. Trois conditions doivent être remplies :\n\n**1. Realm — feature Organizations activée**\n```\nConsole Key","anchor":"organizations-keycloak-iam-c4-obligatoire"},{"id":"v1.0-dev-03-authentication-overview-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"03-authentication-overview","chapterTitle":"Authentification — Concepts & Flow","heading":"Gestion d'erreurs au callback","snippet":"| Cas | Symptôme | Solution |\n|-----|----------|----------|\n| `redirect_uri` mismatch | `400 Invalid redirect_uri` Keycloak | Vérifier exact match URI dans la console Keycloak |\n| `client_id` incorrec","anchor":"gestion-derreurs-au-callback"},{"id":"v1.0-dev-03-authentication-overview-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"03-authentication-overview","chapterTitle":"Authentification — Concepts & Flow","heading":"Aller plus loin","snippet":"- [Implémentation PKCE](04-authentication-implementation) : code complet étape par étape\n- [Discovery](02-discovery) : `start-login` et extraction de `keycloakUrl`\n- [Contexte utilisateur /me](05-me-e","anchor":"aller-plus-loin"},{"id":"v1.0-dev-04-authentication-implementation-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"04-authentication-implementation","chapterTitle":"Authentification — Implémentation PKCE","heading":"Étape 2 — Génération PKCE (TypeScript)","snippet":"```typescript\n// Génération du code_verifier (43-128 chars URL-safe)\nfunction generateCodeVerifier(): string {\n const array = new Uint8Array(32);\n crypto.getRandomValues(array);\n return btoa(String","anchor":"tape-2-gnration-pkce-typescript"},{"id":"v1.0-dev-04-authentication-implementation-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"04-authentication-implementation","chapterTitle":"Authentification — Implémentation PKCE","heading":"Étape 3 — Appel `start-login`","snippet":"```http\nPOST {DISCOVERY_API_URL}/discover/start-login\nContent-Type: application/json\n\n{\n \"host\": \"app.test\",\n \"redirectUri\": \"https://app.test.wakastart.app/api/auth/callback\",\n \"state\": \"550e8400-","anchor":"tape-3-appel-start-login"},{"id":"v1.0-dev-04-authentication-implementation-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"04-authentication-implementation","chapterTitle":"Authentification — Implémentation PKCE","heading":"Étape 4 — Extraction et stockage","snippet":"```typescript\nconst { keycloakUrl } = await startLoginResponse.json();\n\nconst parsed = new URL(keycloakUrl);\nconst realm = parsed.pathname.match(/\\/realms\\/([^/]+)\\//)?.[1];\nconst clientId = parsed","anchor":"tape-4-extraction-et-stockage"},{"id":"v1.0-dev-04-authentication-implementation-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"04-authentication-implementation","chapterTitle":"Authentification — Implémentation PKCE","heading":"Étape 7 — Échange code → tokens (callback)","snippet":"```typescript\n// Handler côté serveur (route /api/auth/callback)\nconst realm = sessionStorage.getItem(\"login_realm\");\nconst clientId = sessionStorage.getItem(\"login_client_id\");\nconst verifier ","anchor":"tape-7-change-code-tokens-callback"},{"id":"v1.0-dev-04-authentication-implementation-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"04-authentication-implementation","chapterTitle":"Authentification — Implémentation PKCE","heading":"Étape 8 — Enrichissement obligatoire","snippet":"```http\nPOST {WAKASTART_BACKEND_URL}/api/auth/enrich\nAuthorization: Bearer {access_token}\n```\n\n**Réponse :**\n```json\n{\n \"token\": \"eyJhbGciOiJIUzI1NiJ9...\",\n \"payload\": {\n \"adminLevel\": \"CustomerA","anchor":"tape-8-enrichissement-obligatoire"},{"id":"v1.0-dev-04-authentication-implementation-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"04-authentication-implementation","chapterTitle":"Authentification — Implémentation PKCE","heading":"Étape 9 — Stockage des cookies","snippet":"```typescript\n// Côté serveur Next.js (route handler ou middleware)\nimport { cookies } from \"next/headers\";\n\nconst cookieStore = await cookies();\n\n// access_token Keycloak RS256\ncookieStore.set(\"keycl","anchor":"tape-9-stockage-des-cookies"},{"id":"v1.0-dev-04-authentication-implementation-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"04-authentication-implementation","chapterTitle":"Authentification — Implémentation PKCE","heading":"Rafraîchissement proactif","snippet":"```http\nPOST /api/auth/token/refresh\nContent-Type: application/json\n\n{ \"refreshToken\": \"xxx\", \"accessToken\": \"xxx\" }\n```\n\n**Réponse :** nouveaux `access_token`, `refresh_token`, `enriched_token`.\n\n**S","anchor":"rafrachissement-proactif"},{"id":"v1.0-dev-04-authentication-implementation-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"04-authentication-implementation","chapterTitle":"Authentification — Implémentation PKCE","heading":"Logout","snippet":"```http\nPOST /api/auth/logout\nContent-Type: application/json\n\n{ \"refreshToken\": \"xxx\" }\n```\n\nInvalide le refresh token côté Keycloak. **Complétez côté frontend :**\n\n```typescript\n// Supprimer les cook","anchor":"logout"},{"id":"v1.0-dev-04-authentication-implementation-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"04-authentication-implementation","chapterTitle":"Authentification — Implémentation PKCE","heading":"Bonnes pratiques","snippet":"- Toujours générer un nouveau `code_verifier` à chaque tentative de login.\n- Vérifier le `state` CSRF au retour du callback (comparer sessionStorage vs query param).\n- Stocker les tokens **uniquement*","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-04-authentication-implementation-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"04-authentication-implementation","chapterTitle":"Authentification — Implémentation PKCE","heading":"Pièges classiques","snippet":"- **Boucle de refresh infinie** : sur `401`, tenter le refresh une seule fois puis redirect login.\n- **`redirect_uri` avec trailing slash** : `https://app.test/callback` ≠ `https://app.test/callback/`","anchor":"piges-classiques"},{"id":"v1.0-dev-04-authentication-implementation-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"04-authentication-implementation","chapterTitle":"Authentification — Implémentation PKCE","heading":"Aller plus loin","snippet":"- [Discovery](02-discovery) : `start-login` et extraction de `keycloakUrl`\n- [Contexte utilisateur /me](05-me-endpoint-payload) : étape post-auth\n- [Pièges classiques](17-pitfalls) : diagnostic des er","anchor":"aller-plus-loin"},{"id":"v1.0-dev-05-me-endpoint-payload-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Pourquoi cette étape","snippet":"Le JWT Keycloak contient l'identité minimale (sub, email, niveaux admin). Mais pour construire une UI conditionnelle (masquer/afficher des boutons selon les droits, afficher le bon nom d'organisation,","anchor":"pourquoi-cette-tape"},{"id":"v1.0-dev-05-me-endpoint-payload-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Concepts clés","snippet":"- **adminLevel** : niveau hiérarchique admin de l'utilisateur (WakaAdmin → None).\n- **appRights** : liste de droits applicatifs de type `resource.action` accumulés depuis les profils. Détail de la for","anchor":"concepts-cls"},{"id":"v1.0-dev-05-me-endpoint-payload-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Appel","snippet":"```http\nGET /api/me\nAuthorization: Bearer \nx-enriched-token: \n```\n\nLes deux headers sont requis. La réponse est la même que l'utilisateur appelle avec un Bearer","anchor":"appel"},{"id":"v1.0-dev-05-me-endpoint-payload-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Réponse complète","snippet":"```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"wid\": \"WKST05\",\n \"email\": \"john@acme.com\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"keycloakId\": \"kc-550e8400-e29b-41d4-a716-4466554","anchor":"rponse-complte"},{"id":"v1.0-dev-05-me-endpoint-payload-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Description de chaque champ","snippet":"","anchor":"description-de-chaque-champ"},{"id":"v1.0-dev-05-me-endpoint-payload-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Identité","snippet":"| Champ | Type | Description |\n|-------|------|-------------|\n| `id` | UUID | Identifiant interne en base |\n| `wid` | string | Identifiant court (6 chars) pour les URLs |\n| `email` | string | Email de","anchor":"identit"},{"id":"v1.0-dev-05-me-endpoint-payload-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Niveaux d'accès","snippet":"| Champ | Type | Description |\n|-------|------|-------------|\n| `adminLevel` | string | Niveau admin hiérarchique (voir tableau ci-dessous) |\n\n> Le champ `userLevel` **n'est plus retourné par `/me`** ","anchor":"niveaux-daccs"},{"id":"v1.0-dev-05-me-endpoint-payload-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Contexte multi-tenant","snippet":"| Champ | Type | Description |\n|-------|------|-------------|\n| `customer` | object | Customer auquel l'utilisateur appartient |\n| `partner` | object | Partner parent du customer |\n| `network` | objec","anchor":"contexte-multi-tenant"},{"id":"v1.0-dev-05-me-endpoint-payload-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Rôles HDS","snippet":"| Champ | Type | Description |\n|-------|------|-------------|\n| `hdsRoles` | string[] | Rôles HDS (Healthcare Data Security) : `HDS_ADMIN`, `HDS_PATIENT`, etc. |\n\n> Le champ `wakaRoles` (rôles métier ","anchor":"rles-hds"},{"id":"v1.0-dev-05-me-endpoint-payload-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Équipes","snippet":"`appRights` dans le contexte équipe est un champ libre encodé sur la team (distinct des `appRights` globaux de l'utilisateur).","anchor":"quipes"},{"id":"v1.0-dev-05-me-endpoint-payload-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Profils et droits applicatifs","snippet":"- `profiles` : profils assignés. Un profil = un ensemble de `AppRight` côté DB.\n- `appRights` : tableau dédupliqué et fusionné de tous les droits provenant de tous les profils. Format : `{resource}.{a","anchor":"profils-et-droits-applicatifs"},{"id":"v1.0-dev-05-me-endpoint-payload-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Ce qui est dans /me vs dans le JWT","snippet":"> [!WARNING]\n> Le JWT enrichi (wakaToken) est signé et doit tenir sous la limite de 4 Ko d'un cookie. Plusieurs claims autrefois présents en ont été retirés et ne sont plus disponibles **que** via `/m","anchor":"ce-qui-est-dans-me-vs-dans-le-jwt"},{"id":"v1.0-dev-05-me-endpoint-payload-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"05-me-endpoint-payload","chapterTitle":"Contexte utilisateur — Structure du payload /me","heading":"Aller plus loin","snippet":"- [Cache et invalidation /me](06-me-endpoint-caching) : quand appeler `/me`, mise en cache, invalidation\n- [Contrôle d'accès](07-access-control-model) : comment utiliser `appRights` dans vos guards\n- ","anchor":"aller-plus-loin"},{"id":"v1.0-dev-06-me-endpoint-caching-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"06-me-endpoint-caching","chapterTitle":"Contexte utilisateur — Cache & Invalidation","heading":"Quand appeler /me","snippet":"| Situation | Appeler /me ? |\n|-----------|:-------------:|\n| **Au login** (après enrichissement) | Oui — stocker dans le context |\n| Après un **refresh token** | Oui — les droits peuvent avoir changé","anchor":"quand-appeler-me"},{"id":"v1.0-dev-06-me-endpoint-caching-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"06-me-endpoint-caching","chapterTitle":"Contexte utilisateur — Cache & Invalidation","heading":"Pattern React recommandé — AuthContext","snippet":"```typescript\n// lib/auth-context.tsx\nimport { createContext, useContext, useState, useCallback } from \"react\";\n\ninterface MeUser {\n id: string;\n wid: string;\n email: string;\n firstName: string;\n ","anchor":"pattern-react-recommand-authcontext"},{"id":"v1.0-dev-06-me-endpoint-caching-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"06-me-endpoint-caching","chapterTitle":"Contexte utilisateur — Cache & Invalidation","heading":"Mise en cache et TTL recommandé","snippet":"`/me` est appelé une fois au login. La réponse est stable tant que :\n- Les droits de l'utilisateur n'ont pas été modifiés par un admin.\n- Le token n'a pas été rafraîchi.\n\n**Stratégie recommandée :**\n1","anchor":"mise-en-cache-et-ttl-recommand"},{"id":"v1.0-dev-06-me-endpoint-caching-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"06-me-endpoint-caching","chapterTitle":"Contexte utilisateur — Cache & Invalidation","heading":"Synchronisation après refresh token","snippet":"```typescript\n// app/api/auth/refresh/route.ts\nexport async function POST(req: NextRequest) {\n const cookieStore = await cookies();\n const refreshToken = cookieStore.get(\"refresh_token\")?.value;\n\n ","anchor":"synchronisation-aprs-refresh-token"},{"id":"v1.0-dev-06-me-endpoint-caching-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"06-me-endpoint-caching","chapterTitle":"Contexte utilisateur — Cache & Invalidation","heading":"Bonnes pratiques","snippet":"- Ne stockez pas le payload `/me` dans `localStorage` — il contient des droits sensibles.\n- Utilisez les `appRights` uniquement pour l'**affichage conditionnel** côté front. Le backend est la source d","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-06-me-endpoint-caching-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"06-me-endpoint-caching","chapterTitle":"Contexte utilisateur — Cache & Invalidation","heading":"Pièges classiques","snippet":"- **Droits stale** : les droits sont modifiés par un admin mais le cache `/me` n'est pas invalidé. Ajouter un mécanisme de polling léger ou une notification WebSocket.\n- **`appRights` vide mais user a","anchor":"piges-classiques"},{"id":"v1.0-dev-06-me-endpoint-caching-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"06-me-endpoint-caching","chapterTitle":"Contexte utilisateur — Cache & Invalidation","heading":"Aller plus loin","snippet":"- [Contrôle d'accès](07-access-control-model) : comment utiliser `appRights` dans vos guards\n- [Utilisation de l'API](10-api-conventions) : comment passer les tokens dans vos requêtes","anchor":"aller-plus-loin"},{"id":"v1.0-dev-07-access-control-model-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"07-access-control-model","chapterTitle":"Contrôle d'accès — Modèle & Cascade","heading":"Concepts clés","snippet":"- **adminLevel** : niveau hiérarchique, détermine la portée des opérations CRUD.\n- **appRights** : droits fins sur des ressources spécifiques (`users.create`, `infra.deploy`…), dérivés des profils. Le","anchor":"concepts-cls"},{"id":"v1.0-dev-07-access-control-model-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"07-access-control-model","chapterTitle":"Contrôle d'accès — Modèle & Cascade","heading":"Les 2 vecteurs de droits","snippet":"","anchor":"les-2-vecteurs-de-droits"},{"id":"v1.0-dev-07-access-control-model-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"07-access-control-model","chapterTitle":"Contrôle d'accès — Modèle & Cascade","heading":"1. `adminLevel` — portée hiérarchique","snippet":"Contrôle **qui peut voir et modifier quoi** selon la position dans la hiérarchie multi-tenant.\n\n```\nWakaAdmin → Tout (plateforme complète, tous les Partners)\nOwnerAdmin → Tout (propriétaire du ","anchor":"1-adminlevel-porte-hirarchique"},{"id":"v1.0-dev-07-access-control-model-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"07-access-control-model","chapterTitle":"Contrôle d'accès — Modèle & Cascade","heading":"2. `appRights` — droits applicatifs fins","snippet":"Droits de type `{resource}.{action}` accumulés depuis les profils de l'utilisateur.\n\n**Format :** `resource.action` ou `resource.sub-resource.action`\n\nExemples :\n```\npartners.read users.creat","anchor":"2-apprights-droits-applicatifs-fins"},{"id":"v1.0-dev-07-access-control-model-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"07-access-control-model","chapterTitle":"Contrôle d'accès — Modèle & Cascade","heading":"Cascade de features","snippet":"Une feature doit être activée à **trois niveaux** pour être disponible :\n\n```mermaid\nflowchart TD\n A[\"AppFeature.isEnabled = true\"] --> D{ET}\n B[\"NetworkAppFeature.isEnabled = true\"] --> D\n C[\"Cust","anchor":"cascade-de-features"},{"id":"v1.0-dev-07-access-control-model-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"07-access-control-model","chapterTitle":"Contrôle d'accès — Modèle & Cascade","heading":"Vérification combinée via `/token/authorize`","snippet":"Pour des vérifications complexes (admin level + rôle + droit) en un seul appel :\n\n```http\nPOST /api/token/authorize\nx-api-key: sk_live_...\nContent-Type: application/json\n\n{\n \"token\": \"eyJ...\",\n \"che","anchor":"vrification-combine-via-tokenauthorize"},{"id":"v1.0-dev-07-access-control-model-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"07-access-control-model","chapterTitle":"Contrôle d'accès — Modèle & Cascade","heading":"Bonnes pratiques","snippet":"- **Principe du moindre privilège** : n'accordez que les droits strictement nécessaires dans les profils.\n- **Backend = autorité** : vérifiez toujours les droits côté serveur. Le frontend ne fait que ","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-07-access-control-model-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"07-access-control-model","chapterTitle":"Contrôle d'accès — Modèle & Cascade","heading":"Pièges classiques","snippet":"- **Confondre trois concepts voisins** : `adminLevel` (`ADMIN`, `TEAM`, `INVITE`, `USER`, `EXTERN`, `NONE`) est la portée administrative sur la hiérarchie ; `teamLevel` (`ADMIN`, `MANAGER`, `MEMBER`, ","anchor":"piges-classiques"},{"id":"v1.0-dev-07-access-control-model-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"07-access-control-model","chapterTitle":"Contrôle d'accès — Modèle & Cascade","heading":"Aller plus loin","snippet":"- [Implémentation guards & hooks](08-access-control-implementation) : code complet frontend et backend\n- [Feature flags et cascade](09-access-control-features) : AppFeature, NetworkAppFeature, Custome","anchor":"aller-plus-loin"},{"id":"v1.0-dev-08-access-control-implementation-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"08-access-control-implementation","chapterTitle":"Contrôle d'accès — Guards & Hooks","heading":"Implémentation côté frontend","snippet":"","anchor":"implmentation-ct-frontend"},{"id":"v1.0-dev-08-access-control-implementation-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"08-access-control-implementation","chapterTitle":"Contrôle d'accès — Guards & Hooks","heading":"Hook `useAppRights`","snippet":"```typescript\n// hooks/use-app-rights.ts\nimport { useAuth } from \"@/lib/auth-context\";\n\nexport function useAppRights() {\n const { user } = useAuth();\n const appRights = user?.appRights ?? [];\n\n ret","anchor":"hook-useapprights"},{"id":"v1.0-dev-08-access-control-implementation-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"08-access-control-implementation","chapterTitle":"Contrôle d'accès — Guards & Hooks","heading":"Composant ``","snippet":"```typescript\n// components/protected.tsx\nimport { useAppRights } from \"@/hooks/use-app-rights\";\n\ninterface ProtectedProps {\n right?: string;\n anyRight?: string[];\n allRights?: string[];\n adminLev","anchor":"composant-protected"},{"id":"v1.0-dev-08-access-control-implementation-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"08-access-control-implementation","chapterTitle":"Contrôle d'accès — Guards & Hooks","heading":"Implémentation côté backend NestJS (dans votre Wakapp)","snippet":"Si votre Wakapp a son propre backend, vérifiez les droits en **déléguant à l'API d'autorisation** WakaStart : `POST /api/token/authorize`.\n\n> **À ne pas faire** — Ne vérifiez **jamais** la signature d","anchor":"implmentation-ct-backend-nestjs-dans-votre-wakapp"},{"id":"v1.0-dev-08-access-control-implementation-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"08-access-control-implementation","chapterTitle":"Contrôle d'accès — Guards & Hooks","heading":"Décorateur `@RequireAppRight`","snippet":"```typescript\n// decorators/require-app-right.decorator.ts\nimport { SetMetadata } from \"@nestjs/common\";\n\nexport const REQUIRED_RIGHT_KEY = \"requiredRight\";\nexport const RequireAppRight = (right: stri","anchor":"dcorateur-requireappright"},{"id":"v1.0-dev-08-access-control-implementation-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"08-access-control-implementation","chapterTitle":"Contrôle d'accès — Guards & Hooks","heading":"Guard `AppRightGuard` — délégation à `/api/token/authorize`","snippet":"```typescript\n// guards/app-right.guard.ts\nimport { Injectable, CanActivate, ExecutionContext, ForbiddenException } from \"@nestjs/common\";\nimport { Reflector } from \"@nestjs/core\";\nimport { REQUIRED_R","anchor":"guard-apprightguard-dlgation-apitokenauthorize"},{"id":"v1.0-dev-08-access-control-implementation-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"08-access-control-implementation","chapterTitle":"Contrôle d'accès — Guards & Hooks","heading":"Usage dans un contrôleur NestJS","snippet":"```typescript\n@Controller(\"users\")\n@UseGuards(AppRightGuard)\nexport class UsersController {\n @Post()\n @RequireAppRight(\"users.create\")\n async createUser(@Body() dto: CreateUserDto) {\n // ...\n }","anchor":"usage-dans-un-contrleur-nestjs"},{"id":"v1.0-dev-08-access-control-implementation-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"08-access-control-implementation","chapterTitle":"Contrôle d'accès — Guards & Hooks","heading":"Bonnes pratiques","snippet":"- **Logging des refus** : loggez les `403` avec le droit manquant (mais jamais le token complet).\n- **Invalidation du cache** : après une modification de profil par un admin, l'utilisateur doit se re-","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-08-access-control-implementation-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"08-access-control-implementation","chapterTitle":"Contrôle d'accès — Guards & Hooks","heading":"Aller plus loin","snippet":"- [Feature flags et cascade](09-access-control-features) : AppFeature, NetworkAppFeature, CustomerAppFeature\n- [Contexte utilisateur /me](05-me-endpoint-payload) : source des droits\n- [Référence des e","anchor":"aller-plus-loin"},{"id":"v1.0-dev-09-access-control-features-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"09-access-control-features","chapterTitle":"Contrôle d'accès — Feature Flags","heading":"Modèle de cascade","snippet":"Une feature est le résultat de trois activations indépendantes. Si **une seule** est `false`, la feature est indisponible pour l'utilisateur :\n\n```mermaid\nflowchart LR\n A[\"App\\nAppFeature.isEnabled\"]","anchor":"modle-de-cascade"},{"id":"v1.0-dev-09-access-control-features-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"09-access-control-features","chapterTitle":"Contrôle d'accès — Feature Flags","heading":"Features standard de la plateforme","snippet":"| Feature | Description |\n|---------|-------------|\n| `invitations` | Flux d'invitations utilisateur (envoi email, acceptation, provisioning) |\n| `antivirus` | Scan antivirus des fichiers uploadés (Cl","anchor":"features-standard-de-la-plateforme"},{"id":"v1.0-dev-09-access-control-features-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"09-access-control-features","chapterTitle":"Contrôle d'accès — Feature Flags","heading":"Utilisation côté frontend","snippet":"","anchor":"utilisation-ct-frontend"},{"id":"v1.0-dev-09-access-control-features-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"09-access-control-features","chapterTitle":"Contrôle d'accès — Feature Flags","heading":"Vérification simple","snippet":"```typescript\nimport { useEffect, useState } from \"react\";\nimport { useAuth } from \"@/lib/auth-context\";\n\nfunction InvitationsSection() {\n const { user } = useAuth();\n const [enabled, setEnabled] = ","anchor":"vrification-simple"},{"id":"v1.0-dev-09-access-control-features-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"09-access-control-features","chapterTitle":"Contrôle d'accès — Feature Flags","heading":"Combinaison feature + droit","snippet":"```tsx\n// Résolvez la feature en amont (cf. exemple ci-dessus), puis combinez avec le droit :\n{enabled && (\n \n \n \n)}\n```\n\n> *","anchor":"combinaison-feature-droit"},{"id":"v1.0-dev-09-access-control-features-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"09-access-control-features","chapterTitle":"Contrôle d'accès — Feature Flags","heading":"Activation via l'API","snippet":"Les endpoints réels vivent sous `/api/config/app-features` — pas de route dédiée par `customerWid`/`appWid` + nom de feature :\n\n```http\nGET /api/config/app-features/check/{customerWid}/{featureCode}\nA","anchor":"activation-via-lapi"},{"id":"v1.0-dev-09-access-control-features-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"09-access-control-features","chapterTitle":"Contrôle d'accès — Feature Flags","heading":"Guard backend NestJS — RequireFeature","snippet":"Si votre Wakapp expose des endpoints qui nécessitent une feature active :\n\n```typescript\n// decorators/require-feature.decorator.ts\nimport { SetMetadata } from \"@nestjs/common\";\n\nexport const REQUIRED","anchor":"guard-backend-nestjs-requirefeature"},{"id":"v1.0-dev-09-access-control-features-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"09-access-control-features","chapterTitle":"Contrôle d'accès — Feature Flags","heading":"Bonnes pratiques","snippet":"- **Vérifier la feature avant d'afficher l'UI** : ne pas attendre le `403` de l'API pour masquer un bouton.\n- **Pas de feature par défaut** : si `GET app-features/check/...` renvoie `enabled: false` (","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-09-access-control-features-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"09-access-control-features","chapterTitle":"Contrôle d'accès — Feature Flags","heading":"Pièges classiques","snippet":"- **Feature absente ≠ erreur** : si `app-features/enabled/{customerWid}` renvoie un tableau vide, ce n'est pas un bug — le customer n'a simplement aucune feature activée.\n- **Ne pas confondre feature ","anchor":"piges-classiques"},{"id":"v1.0-dev-09-access-control-features-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"09-access-control-features","chapterTitle":"Contrôle d'accès — Feature Flags","heading":"Aller plus loin","snippet":"- [Modèle de droits](07-access-control-model) : adminLevel, appRights\n- [Invitations](18-invitations-create) : exemple complet de feature + droit combinés","anchor":"aller-plus-loin"},{"id":"v1.0-dev-12-best-practices-security-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"1. Tokens en cookies HttpOnly uniquement","snippet":"```typescript\n// BIEN : cookie HttpOnly, jamais accessible depuis JavaScript\ncookieStore.set(\"keycloak_token\", token, { httpOnly: true, secure: true });\n\n// MAL : accessible depuis JS, vulnérable aux ","anchor":"1-tokens-en-cookies-httponly-uniquement"},{"id":"v1.0-dev-12-best-practices-security-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"2. PKCE obligatoire — pas de flow implicite","snippet":"Le flow implicite (`response_type=token`) est déprécié et interdit. PKCE S256 est l'unique flow supporté.","anchor":"2-pkce-obligatoire-pas-de-flow-implicite"},{"id":"v1.0-dev-12-best-practices-security-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"3. Pas de secrets côté client","snippet":"```typescript\n// BIEN : API key dans une variable d'env côté serveur\nconst apiKey = process.env.WAKASTART_API_KEY; // server-only\n\n// MAL : exposé dans le bundle frontend\nconst apiKey = \"sk_live_...\";","anchor":"3-pas-de-secrets-ct-client"},{"id":"v1.0-dev-12-best-practices-security-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"4. Backend vérifie toujours, frontend masque","snippet":"```typescript\n// BIEN côté backend NestJS Wakapp\n@UseGuards(AppRightGuard)\n@RequireAppRight(\"users.delete\")\nasync deleteUser(@Param(\"id\") id: string) { ... }\n\n// BIEN côté frontend (masquage UI unique","anchor":"4-backend-vrifie-toujours-frontend-masque"},{"id":"v1.0-dev-12-best-practices-security-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"5. Messages d'erreur génériques côté login","snippet":"```typescript\n// BIEN : ne révèle pas si l'email est connu\ncatch (err) {\n setError(\"Impossible de se connecter. Vérifiez vos identifiants et réessayez.\");\n}\n\n// MAL : révèle l'existence du compte\ncat","anchor":"5-messages-derreur-gnriques-ct-login"},{"id":"v1.0-dev-12-best-practices-security-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"6. HTTPS en production, CSP renforcée","snippet":"```typescript\n// next.config.ts\nconst securityHeaders = [\n { key: \"Strict-Transport-Security\", value: \"max-age=63072000; includeSubDomains; preload\" },\n { key: \"X-Content-Type-Options\", value: \"nosn","anchor":"6-https-en-production-csp-renforce"},{"id":"v1.0-dev-12-best-practices-security-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"7. Ne jamais logger les tokens","snippet":"```typescript\n// BIEN : redacter le header Authorization dans les logs\nlogger.info(\"API call\", {\n url: apiUrl,\n headers: { ...headers, Authorization: \"[REDACTED]\", \"x-enriched-token\": \"[REDACTED]\" }","anchor":"7-ne-jamais-logger-les-tokens"},{"id":"v1.0-dev-12-best-practices-security-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"8. Ne jamais détenir `INTERNAL_API_SECRET`","snippet":"Ce secret n'est utilisé qu'entre services internes Wakastellar. Aucune Wakapp tierce n'en a besoin et n'en aura jamais besoin.\n\n---","anchor":"8-ne-jamais-dtenir-internal_api_secret"},{"id":"v1.0-dev-12-best-practices-security-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"Gestion des erreurs 401, 403, 429","snippet":"```typescript\nasync function apiFetch(url: string, options: RequestInit) {\n const res = await fetch(url, options);\n\n switch (res.status) {\n case 401:\n // Token expiré → tenter refresh, puis ","anchor":"gestion-des-erreurs-401-403-429"},{"id":"v1.0-dev-12-best-practices-security-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"Tests de sécurité","snippet":"","anchor":"tests-de-scurit"},{"id":"v1.0-dev-12-best-practices-security-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"21. Ne jamais tester contre la production","snippet":"Utilisez un Customer de test dédié (avec `CUSTOMER_WID=TST001`) et une App de test.","anchor":"21-ne-jamais-tester-contre-la-production"},{"id":"v1.0-dev-12-best-practices-security-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"22. Mocker les réponses Discovery et enrich en tests unitaires","snippet":"```typescript\n// jest.setup.ts\njest.mock(\"@/lib/api/discovery\", () => ({\n startLogin: jest.fn().mockResolvedValue({\n keycloakUrl: \"https://auth.test/realms/test/protocol/openid-connect/auth?client","anchor":"22-mocker-les-rponses-discovery-et-enrich-en-tests-unitaires"},{"id":"v1.0-dev-12-best-practices-security-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"23. Tests d'intégration avec un compte service","snippet":"Pour les tests e2e, utilisez une clé API dédiée (`sk_test_...`) avec des droits minimaux.\n\n---","anchor":"23-tests-dintgration-avec-un-compte-service"},{"id":"v1.0-dev-12-best-practices-security-13","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"Checklist sécurité pré-production","snippet":"- [ ] Tokens stockés en cookies HttpOnly (jamais localStorage)\n- [ ] Proxy serveur implémenté (browser ne contacte pas directement l'API)\n- [ ] PKCE S256 (pas de flow implicite)\n- [ ] HTTPS avec HSTS ","anchor":"checklist-scurit-pr-production"},{"id":"v1.0-dev-12-best-practices-security-14","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"12-best-practices-security","chapterTitle":"Bonnes pratiques — Sécurité","heading":"Aller plus loin","snippet":"- [Performance & Observabilité](13-best-practices-perf-observability) : cache, retry, métriques, tracing\n- [Pièges classiques](17-pitfalls) : diagnostic des erreurs fréquentes","anchor":"aller-plus-loin"},{"id":"v1.0-dev-13-best-practices-perf-observability-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"Performance","snippet":"","anchor":"performance"},{"id":"v1.0-dev-13-best-practices-perf-observability-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"9. Cacher /me — un seul appel au login","snippet":"```typescript\n// BIEN : stocker dans un React context, ne jamais re-fetcher à la navigation\nconst AuthProvider = ({ children }) => {\n const [user, setUser] = useState(null);\n\n useEffect(() => {\n ","anchor":"9-cacher-me-un-seul-appel-au-login"},{"id":"v1.0-dev-13-best-practices-perf-observability-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"10. Refresh proactif avant l'expiration","snippet":"```typescript\n// BIEN : vérifier exp - now < 60s et rafraîchir avant l'expiration\nconst REFRESH_THRESHOLD = 60; // secondes\n\nfunction scheduleTokenRefresh(expiresIn: number) {\n const refreshIn = Math","anchor":"10-refresh-proactif-avant-lexpiration"},{"id":"v1.0-dev-13-best-practices-perf-observability-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"11. Pagination — ne jamais charger tout","snippet":"```typescript\n// BIEN : paginer, limit max = 100\nconst { data } = await apiGet(\"config/users\", { page: \"1\", limit: \"50\" });\n\n// MAL : tenter de tout charger\nconst { data } = await apiGet(\"config/users","anchor":"11-pagination-ne-jamais-charger-tout"},{"id":"v1.0-dev-13-best-practices-perf-observability-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"12. TanStack Query — staleTime adapté à la criticité","snippet":"```typescript\n// Données qui changent rarement (branding, runtime-config) : 5 minutes\nuseQuery({\n queryKey: [\"runtime-config\"],\n queryFn: fetchRuntimeConfig,\n staleTime: 5 * 60 * 1000,\n});\n\n// Donn","anchor":"12-tanstack-query-staletime-adapt-la-criticit"},{"id":"v1.0-dev-13-best-practices-perf-observability-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"Architecture","snippet":"","anchor":"architecture"},{"id":"v1.0-dev-13-best-practices-perf-observability-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"13. Proxy serveur pour tous les appels API","snippet":"Le browser ne doit jamais appeler directement la Public API.\n\n```\nBrowser → /api/proxy/[...path] (route Next.js) → Public API\n └── lit les cookies HttpOnly\n └── ajoute Author","anchor":"13-proxy-serveur-pour-tous-les-appels-api"},{"id":"v1.0-dev-13-best-practices-perf-observability-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"14. Séparer Discovery et API","snippet":"```typescript\n// BIEN : Discovery utilisé une seule fois, avant l'auth\nconst { keycloakUrl } = await discoverStartLogin({ host });\nwindow.location.assign(keycloakUrl);\n\n// MAL : appeler Discovery aprè","anchor":"14-sparer-discovery-et-api"},{"id":"v1.0-dev-13-best-practices-perf-observability-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"15. Respecter la hiérarchie dans votre modèle de données","snippet":"```typescript\n// Vos entités doivent refléter la hiérarchie Wakastart\ninterface AppContext {\n partnerId: string; // pid du wakaToken\n networkId: string; // nid\n customerId: string; // cid\n appId","anchor":"15-respecter-la-hirarchie-dans-votre-modle-de-donnes"},{"id":"v1.0-dev-13-best-practices-perf-observability-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"16. Utiliser les WIDs dans les URLs","snippet":"```\nBIEN : /users/WKST05 (lisible, stable)\nMAL : /users/550e8400-... (UUID interne)\n```\n\n---","anchor":"16-utiliser-les-wids-dans-les-urls"},{"id":"v1.0-dev-13-best-practices-perf-observability-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"Observabilité","snippet":"","anchor":"observabilit"},{"id":"v1.0-dev-13-best-practices-perf-observability-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"17. Propager le `x-trace-id`","snippet":"```typescript\n// Inclure l'ID de trace dans toutes vos requêtes API\nconst traceId = crypto.randomUUID();\nheaders[\"x-trace-id\"] = traceId;\n\n// Logger côté frontend avec le même ID\nlogger.info(\"API call","anchor":"17-propager-le-x-trace-id"},{"id":"v1.0-dev-13-best-practices-perf-observability-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"18. Métriques recommandées","snippet":"Exposez des métriques Prometheus depuis votre Wakapp :\n\n```\nwakapp_api_calls_total{endpoint, status}\nwakapp_token_refresh_total{success}\nwakapp_invitations_created_total{customer}\nwakapp_invitations_a","anchor":"18-mtriques-recommandes"},{"id":"v1.0-dev-13-best-practices-perf-observability-13","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"19. Structured logging","snippet":"```typescript\n// BIEN : JSON structuré, parsable par Loki / CloudWatch\nlogger.info({\n event: \"user_login_success\",\n userId: user.wid,\n customerId: user.customer.wid,\n adminLevel: user.adminLevel,\n","anchor":"19-structured-logging"},{"id":"v1.0-dev-13-best-practices-perf-observability-14","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"Checklist performance pré-production","snippet":"- [ ] Refresh proactif implémenté (threshold 60s)\n- [ ] Rate limit géré (backoff exponentiel)\n- [ ] /me chargé une fois, mis en cache, invalidé au refresh\n- [ ] runtime-config chargé une fois au démar","anchor":"checklist-performance-pr-production"},{"id":"v1.0-dev-13-best-practices-perf-observability-15","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"13-best-practices-perf-observability","chapterTitle":"Bonnes pratiques — Performance & Observabilité","heading":"Aller plus loin","snippet":"- [Headers & Rate limits](11-api-headers-rate-limits) : backoff exponentiel détaillé\n- [Pièges classiques](17-pitfalls) : diagnostic des problèmes de performance","anchor":"aller-plus-loin"},{"id":"v1.0-dev-17-pitfalls-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"1. « Aucun realm n'est associé à ce sous-domaine »","snippet":"**Symptôme :** `start-login` retourne `404 not_found`.\n\n| Cause | Diagnostic | Solution |\n|-------|-----------|----------|\n| Extraction du subdomain incorrecte | Logs Discovery : `host=\"app\"` au lieu ","anchor":"1-aucun-realm-nest-associ-ce-sous-domaine-"},{"id":"v1.0-dev-17-pitfalls-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"2. « Invalid client or Invalid client credentials » au callback","snippet":"**Symptôme :** Le handler `/api/auth/callback` POST retourne `401` avec ce message Keycloak.\n\n| Cause | Diagnostic | Solution |\n|-------|-----------|----------|\n| Client OIDC en mode `Client authentic","anchor":"2-invalid-client-or-invalid-client-credentials-au-callback"},{"id":"v1.0-dev-17-pitfalls-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"3. « Token enrichi manquant » sur tous les appels API","snippet":"**Symptôme :** L'utilisateur est connecté (cookies existants, `/me` répond), mais tous les appels proxifiés vers les services downstream retournent `401 Token enrichi manquant ou invalide`.\n\n| Cause |","anchor":"3-token-enrichi-manquant-sur-tous-les-appels-api"},{"id":"v1.0-dev-17-pitfalls-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"4. Claim `organization` absent — dashboard vide","snippet":"**Symptôme :** L'utilisateur se connecte sans erreur, mais le dashboard est vide de droits et `/me` retourne `appRights: []`.\n\n**Cause :** Le token Keycloak ne contient pas le claim `organization` req","anchor":"4-claim-organization-absent-dashboard-vide"},{"id":"v1.0-dev-17-pitfalls-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"5. Cookie `sameSite: strict` bloque la session au retour de Keycloak","snippet":"**Symptôme :** Après le redirect Keycloak vers `/api/auth/callback`, les cookies ne sont pas transmis. Le handler ne peut pas lire `pkce_verifier` ou les cookies de session. L'utilisateur est redirigé","anchor":"5-cookie-samesite-strict-bloque-la-session-au-retour-de-keycloak"},{"id":"v1.0-dev-17-pitfalls-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"6. Build Next.js du container échoue — EACCES sur `.next/cache/images`","snippet":"**Symptôme :**\n```\nError: EACCES: permission denied, mkdir '/app/.next/cache/images'\n```\n\n**Cause :** Le `COPY .next ./.next` dans le Dockerfile ne transfère pas les permissions correctes au user non-","anchor":"6-build-nextjs-du-container-choue-eacces-sur-nextcacheimages"},{"id":"v1.0-dev-17-pitfalls-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"7. Rate limit déclenché sur Discovery en intégration initiale","snippet":"**Symptôme :** Après quelques tests rapides, le service Discovery répond `429` pour toutes les requêtes.\n\n**Cause :** En phase d'intégration, les développeurs appellent `start-login` en boucle pour dé","anchor":"7-rate-limit-dclench-sur-discovery-en-intgration-initiale"},{"id":"v1.0-dev-17-pitfalls-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"8. `redirect_uri` avec trailing slash","snippet":"**Symptôme :** `400 invalid_redirect_uri` lors de l'échange token avec Keycloak.\n\n**Cause :** Keycloak compare l'URI de callback **exactement** (sensible au `/` final et au casing).\n\n| Configuré dans ","anchor":"8-redirect_uri-avec-trailing-slash"},{"id":"v1.0-dev-17-pitfalls-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"9. `appRights` vides malgré un profil assigné","snippet":"**Symptôme :** `GET /me` retourne `appRights: []` mais l'utilisateur a bien un profil assigné visible dans l'UI admin.\n\n**Causes et diagnostics :**\n\n| Cause | Diagnostic | Solution |\n|-------|--------","anchor":"9-apprights-vides-malgr-un-profil-assign"},{"id":"v1.0-dev-17-pitfalls-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"10. Email avec majuscules cause un `404 not_found` Discovery","snippet":"**Symptôme :** Lookup par email retourne `{ users: [] }` pour `John@Acme.com` alors que l'utilisateur existe avec `john@acme.com`.\n\n**Cause :** Discovery normalise les emails en **lowercase** avant la","anchor":"10-email-avec-majuscules-cause-un-404-not_found-discovery"},{"id":"v1.0-dev-17-pitfalls-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"Récapitulatif — Checklist de débogage","snippet":"Quand ça ne fonctionne pas, dans l'ordre :\n\n1. **`start-login` retourne `404`** → vérifier `extractSubdomain`, vérifier `network.subdomain` en DB\n2. **`Invalid client` au callback** → `Client authenti","anchor":"rcapitulatif-checklist-de-dbogage"},{"id":"v1.0-dev-17-pitfalls-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"17-pitfalls","chapterTitle":"Pièges classiques d'intégration","heading":"Aller plus loin","snippet":"- [Erreurs courantes — HTTP](15-errors-http) : codes HTTP et messages exacts\n- [Authentification — implémentation](04-authentication-implementation) : flow complet avec code\n- [Référence endpoints](14","anchor":"aller-plus-loin"},{"id":"v1.0-dev-10-api-conventions-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Concepts clés","snippet":"- **Bearer + enriched** : double authentification obligatoire pour les appels frontend.\n- **API Key** : alternative pour les backends serveur-à-serveur.\n- **WID** : identifiant court préféré dans les ","anchor":"concepts-cls"},{"id":"v1.0-dev-10-api-conventions-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Authentification des requêtes","snippet":"","anchor":"authentification-des-requtes"},{"id":"v1.0-dev-10-api-conventions-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Méthode 1 — Bearer JWT + enriched token (frontend)","snippet":"Une requête vers les services downstream **doit** porter **deux** tokens :\n\n```http\nAuthorization: Bearer (RS256, émis par Keycloak)\nx-enriched-token: ","anchor":"mthode-1-bearer-jwt-enriched-token-frontend"},{"id":"v1.0-dev-10-api-conventions-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Méthode 2 — API Key (backend serveur-à-serveur)","snippet":"Les API Keys remplacent entièrement la paire Bearer+enriched. Elles sont scopées à un Customer.\n\n```typescript\nconst response = await fetch(`${WAKASTART_API_URL}/api/config/users`, {\n headers: {\n ","anchor":"mthode-2-api-key-backend-serveur-serveur"},{"id":"v1.0-dev-10-api-conventions-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Conventions REST","snippet":"| Convention | Détail |\n|-----------|--------|\n| **Verbes HTTP** | `GET` (lecture), `POST` (création), `PATCH` (mise à jour partielle), `PUT` (remplacement), `DELETE` (suppression) |\n| **Format date**","anchor":"conventions-rest"},{"id":"v1.0-dev-10-api-conventions-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Format d'erreur unifié","snippet":"```json\n{\n \"statusCode\": 403,\n \"message\": \"Niveau d'administration insuffisant. Requis: CustomerAdmin, Actuel: User\",\n \"error\": \"Forbidden\"\n}\n```\n\nPour les erreurs de validation (400) :\n\n```json\n{\n","anchor":"format-derreur-unifi"},{"id":"v1.0-dev-10-api-conventions-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Pagination","snippet":"Tous les endpoints de liste supportent la pagination par page :\n\n```http\nGET /api/config/users?page=1&limit=20\n```\n\n```json\n{\n \"data\": [\n { \"id\": \"uuid\", \"wid\": \"WKST05\", \"email\": \"john@acme.com\" ","anchor":"pagination"},{"id":"v1.0-dev-10-api-conventions-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Filtres communs","snippet":"```http\nGET /api/config/users?search=john&isActive=true&page=1&limit=20\nGET /api/config/customers?networkId=NET001&page=1\nGET /api/invitations/sent?status=PENDING&page=1&limit=10\n```\n\n---","anchor":"filtres-communs"},{"id":"v1.0-dev-10-api-conventions-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Multi-tenant automatique","snippet":"Les données sont **automatiquement filtrées** selon le scope du token :\n\n| `adminLevel` | Portée des données retournées |\n|-------------|------------------------------|\n| `WakaAdmin` | Toute la platef","anchor":"multi-tenant-automatique"},{"id":"v1.0-dev-10-api-conventions-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Runtime config","snippet":"Pour charger le thème, les langues et le branding de votre app en un seul appel :\n\n```http\nGET /api/apps/{appWid}/runtime-config\nAuthorization: Bearer \nx-enriched-token: \n```\n\n```jso","anchor":"runtime-config"},{"id":"v1.0-dev-10-api-conventions-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Bonnes pratiques","snippet":"- **Proxy serveur** : ne laissez jamais le browser manipuler les cookies ou les tokens directement.\n- **Gestion des 401** : tenter un refresh token, puis redirect vers login. Jamais de boucle infinie.","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-10-api-conventions-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Pièges classiques","snippet":"- **Header `x-enriched-token` absent** : toutes les requêtes frontend retournent `401`.\n- **Filtrage manuel inutile** : ajouter `customerId=xxx` manuellement alors que le backend filtre déjà.\n- **`lim","anchor":"piges-classiques"},{"id":"v1.0-dev-10-api-conventions-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"10-api-conventions","chapterTitle":"Utilisation de l'API — Conventions REST","heading":"Aller plus loin","snippet":"- [Headers & Rate limits](11-api-headers-rate-limits) : headers requis, idempotence, CORS, throttling\n- [Référence des endpoints](14-endpoint-reference) : tableau complet de toutes les routes\n- [Erreu","anchor":"aller-plus-loin"},{"id":"v1.0-dev-11-api-headers-rate-limits-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Headers requis","snippet":"","anchor":"headers-requis"},{"id":"v1.0-dev-11-api-headers-rate-limits-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Appels frontend (Bearer + enriched)","snippet":"```http\nAuthorization: Bearer \nx-enriched-token: \nContent-Type: application/json\n```","anchor":"appels-frontend-bearer-enriched"},{"id":"v1.0-dev-11-api-headers-rate-limits-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Appels backend (API Key)","snippet":"```http\nx-api-key: sk_live_...\nContent-Type: application/json\n```\n\n---","anchor":"appels-backend-api-key"},{"id":"v1.0-dev-11-api-headers-rate-limits-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Headers optionnels","snippet":"| Header | Description |\n|--------|-------------|\n| `Accept-Language` | Langue préférée pour les messages d'erreur (`fr`, `en`). |\n\n> **Pas de `x-trace-id`/`x-request-id`** : ces headers ne sont pas i","anchor":"headers-optionnels"},{"id":"v1.0-dev-11-api-headers-rate-limits-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"CORS","snippet":"L'API WakaStart supporte CORS pour les origines enregistrées. Les règles :\n\n- **Origines autorisées** : configurées dans `ALLOWED_ORIGINS` côté API.\n- **Credentials** : `Access-Control-Allow-Credentia","anchor":"cors"},{"id":"v1.0-dev-11-api-headers-rate-limits-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Idempotence","snippet":"Les opérations `GET`, `PUT` et `DELETE` sont idempotentes. Pour `POST` :\n\n- **Création d'invitation** : si une invitation `PENDING` existe déjà pour le même email + Customer, l'API répond `409 Conflic","anchor":"idempotence"},{"id":"v1.0-dev-11-api-headers-rate-limits-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Rate limiting","snippet":"L'API applique trois niveaux de throttling :\n\n| Niveau | TTL | Limite | Description |\n|--------|-----|--------|-------------|\n| Court | 1 000 ms | 10 req | Anti-burst immédiat |\n| Moyen | 60 000 ms | ","anchor":"rate-limiting"},{"id":"v1.0-dev-11-api-headers-rate-limits-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Limites spécifiques par endpoint","snippet":"| Endpoint | Limite |\n|----------|--------|\n| `POST /discover/start-login` | 5/60s · 20/600s (10 min) · 100/3600s (1 h) |\n| `POST /api/auth/enrich` | Non limité côté BFF (aucun guard/throttler sur cet","anchor":"limites-spcifiques-par-endpoint"},{"id":"v1.0-dev-11-api-headers-rate-limits-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Backoff exponentiel","snippet":"```typescript\nasync function fetchWithRetry(\n url: string,\n options: RequestInit,\n maxRetries = 3\n): Promise {\n for (let attempt = 0; attempt < maxRetries; attempt++) {\n const res = a","anchor":"backoff-exponentiel"},{"id":"v1.0-dev-11-api-headers-rate-limits-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Vérification de droits depuis votre backend","snippet":"```http\nPOST /api/token/authorize\nx-api-key: sk_live_...\nContent-Type: application/json\n\n{\n \"token\": \"eyJ...\",\n \"checks\": {\n \"adminLevel\": { \"requiredLevel\": \"CustomerAdmin\" },\n \"roles\": { \"ro","anchor":"vrification-de-droits-depuis-votre-backend"},{"id":"v1.0-dev-11-api-headers-rate-limits-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Bonnes pratiques","snippet":"- **Headers ne se cumulent pas** : un appel avec `x-api-key` ET `Authorization: Bearer` verra la clé API prévaloir.\n- **Logger le corps de la réponse d'erreur** sur les 5xx (route, méthode, `statusCod","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-11-api-headers-rate-limits-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Pièges classiques","snippet":"- **Appels parallèles au refresh** : si plusieurs requêtes expirent en même temps et tentent toutes un refresh simultané, une seule réussit. Implémenter un mutex côté client.\n- **Rate limit sur les te","anchor":"piges-classiques"},{"id":"v1.0-dev-11-api-headers-rate-limits-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"11-api-headers-rate-limits","chapterTitle":"Utilisation de l'API — Headers & Rate Limits","heading":"Aller plus loin","snippet":"- [Erreurs HTTP](15-errors-http) : codes `429` et `401` détaillés\n- [Bonnes pratiques sécurité](12-best-practices-security) : tokens, secrets, HTTPS","anchor":"aller-plus-loin"},{"id":"v1.0-dev-14-endpoint-reference-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Discovery (pré-auth — publics)","snippet":"Base URL : `{DISCOVERY_API_URL}` (défaut : `http://localhost`)\n\n| Méthode | Route | Throttle | Description |\n|---------|-------|----------|-------------|\n| `GET` | `/discover/email?email=` | 5/60s · 2","anchor":"discovery-pr-auth-publics"},{"id":"v1.0-dev-14-endpoint-reference-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Auth (BFF wakastart — publics pour l'enrich)","snippet":"Base URL : `{WAKASTART_BACKEND_URL}` (défaut : `http://localhost`)\n\n| Méthode | Route | Throttle | Description |\n|---------|-------|----------|-------------|\n| `GET` | `/api/auth/public-key` | — | Clé","anchor":"auth-bff-wakastart-publics-pour-lenrich"},{"id":"v1.0-dev-14-endpoint-reference-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Profil & Droits (Public API)","snippet":"Base URL : `{PUBLIC_API_URL}` (défaut : `http://localhost`) \nAuth : `Authorization: Bearer` + `x-enriched-token` **ou** `x-api-key`\n\n| Méthode | Route | Droit requis | Description |\n|---------|------","anchor":"profil-droits-public-api"},{"id":"v1.0-dev-14-endpoint-reference-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Config — Partners","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/partners` | `partners.read` | Lister les partners |\n| `GET` | `/api/config/part","anchor":"config-partners"},{"id":"v1.0-dev-14-endpoint-reference-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Config — Networks","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/networks` | `networks.read` | Lister les networks |\n| `GET` | `/api/config/netw","anchor":"config-networks"},{"id":"v1.0-dev-14-endpoint-reference-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Config — Customers","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/customers` | `customers.read` | Lister les customers |\n| `GET` | `/api/config/c","anchor":"config-customers"},{"id":"v1.0-dev-14-endpoint-reference-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Config — Users","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/users` | `users.read` | Lister les utilisateurs |\n| `GET` | `/api/config/users/","anchor":"config-users"},{"id":"v1.0-dev-14-endpoint-reference-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Config — Teams","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/teams` | `teams.read` | Lister les équipes |\n| `GET` | `/api/config/teams/:wid`","anchor":"config-teams"},{"id":"v1.0-dev-14-endpoint-reference-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Config — Applications","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/apps` | `apps.read` | Lister les applications |\n| `GET` | `/api/config/apps/:wi","anchor":"config-applications"},{"id":"v1.0-dev-14-endpoint-reference-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Config — Profils et Droits","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/profiles` | `profiles.read` | Lister les profils |\n| `GET` | `/api/config/profi","anchor":"config-profils-et-droits"},{"id":"v1.0-dev-14-endpoint-reference-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Invitations","snippet":"| Méthode | Route | Auth | Droit requis | Description |\n|---------|-------|:----:|:------------:|-------------|\n| `POST` | `/api/invitations` | Bearer / API key | `invitations.create` | Créer une invi","anchor":"invitations"},{"id":"v1.0-dev-14-endpoint-reference-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"API Keys","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/api-keys` | `api-keys.read` | Lister les clés API |\n| `GET` | `/api/config/api-","anchor":"api-keys"},{"id":"v1.0-dev-14-endpoint-reference-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Audit Logs","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/audit/logs` | `audit.read` | Lister les logs d'audit (paginé, filtrable) |\n| `GET` | `","anchor":"audit-logs"},{"id":"v1.0-dev-14-endpoint-reference-13","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Antivirus","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `POST` | `/api/antivirus/scans` | `antivirus.scan` | Soumettre un fichier à scanner (multipart, max ","anchor":"antivirus"},{"id":"v1.0-dev-14-endpoint-reference-14","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Backup & Import","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/backup/applications/:wid` | `apps.read` | Export JSON d'une application |\n| `GET` | `/","anchor":"backup-import"},{"id":"v1.0-dev-14-endpoint-reference-15","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"Traductions & Thèmes","snippet":"| Méthode | Route | Droit requis | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/translations` | — | Lister les clés de traduction |\n| `POST` | `/api/ai-translation/bu","anchor":"traductions-thmes"},{"id":"v1.0-dev-14-endpoint-reference-16","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"14-endpoint-reference","chapterTitle":"Référence des endpoints","heading":"MCP Server (Claude Code Integration)","snippet":"| Méthode | Route | Auth | Description |\n|---------|-------|:----:|-------------|\n| `POST` | `/api/mcp` | Aucune (docs publiques) | Endpoint JSON-RPC 2.0, 5 tools disponibles |\n\n**Tools MCP disponible","anchor":"mcp-server-claude-code-integration"},{"id":"v1.0-dev-15-errors-http-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"Format d'erreur unifié","snippet":"```json\n{\n \"statusCode\": 403,\n \"message\": \"Niveau d'administration insuffisant. Requis: CustomerAdmin, Actuel: User\",\n \"error\": \"Forbidden\"\n}\n```\n\nPour les erreurs de validation (`400`) avec plusie","anchor":"format-derreur-unifi"},{"id":"v1.0-dev-15-errors-http-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"400 — Bad Request","snippet":"Données invalides. Le body n'a pas passé la validation DTO.\n\n**Causes fréquentes :**\n- Email non valide\n- Email de domaine jetable (yopmail, mailinator…)\n- UUID manquant ou malformé\n- Champ obligatoir","anchor":"400-bad-request"},{"id":"v1.0-dev-15-errors-http-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"401 — Unauthorized","snippet":"Authentification manquante ou invalide.","anchor":"401-unauthorized"},{"id":"v1.0-dev-15-errors-http-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"Cas 1 — Token enrichi manquant","snippet":"```json\n{\n \"statusCode\": 401,\n \"message\": \"Token enrichi manquant ou invalide\",\n \"error\": \"Unauthorized\"\n}\n```\n\n**Causes :**\n1. Header `x-enriched-token` absent — vérifier le proxy serveur\n2. Cooki","anchor":"cas-1-token-enrichi-manquant"},{"id":"v1.0-dev-15-errors-http-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"Cas 2 — Token Bearer expiré ou invalide","snippet":"**Action :** Refresh proactif ou redirect login.","anchor":"cas-2-token-bearer-expir-ou-invalide"},{"id":"v1.0-dev-15-errors-http-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"Cas 3 — API Key invalide","snippet":"```json\n{\n \"statusCode\": 401,\n \"message\": \"Cle API invalide\",\n \"error\": \"Unauthorized\"\n}\n```\n\n> Le message exact varie selon la cause (clé absente, invalide ou expirée — voir [Erreurs métier](16-er","anchor":"cas-3-api-key-invalide"},{"id":"v1.0-dev-15-errors-http-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"402 — Payment Required","snippet":"Crédits insuffisants pour une opération consommant des crédits.\n\n```json\n{\n \"statusCode\": 402,\n \"message\": \"Insufficient credits\",\n \"error\": \"Payment Required\"\n}\n```\n\n**Action :** Rediriger vers la","anchor":"402-payment-required"},{"id":"v1.0-dev-15-errors-http-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"403 — Forbidden","snippet":"L'utilisateur est authentifié mais n'a pas les droits nécessaires.","anchor":"403-forbidden"},{"id":"v1.0-dev-15-errors-http-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"Cas 1 — Niveau admin insuffisant","snippet":"```json\n{\n \"statusCode\": 403,\n \"message\": \"Niveau d'administration insuffisant. Requis: CustomerAdmin, Actuel: User\",\n \"error\": \"Forbidden\"\n}\n```","anchor":"cas-1-niveau-admin-insuffisant"},{"id":"v1.0-dev-15-errors-http-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"Cas 2 — Droit applicatif manquant","snippet":"```json\n{\n \"statusCode\": 403,\n \"message\": \"Droit requis : users.create\",\n \"error\": \"Forbidden\"\n}\n```","anchor":"cas-2-droit-applicatif-manquant"},{"id":"v1.0-dev-15-errors-http-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"Cas 3 — Feature désactivée","snippet":"```json\n{\n \"statusCode\": 403,\n \"message\": \"La fonctionnalité invitation n'est pas activée pour ce customer\",\n \"error\": \"Forbidden\"\n}\n```\n\n**Action :** Afficher un message clair à l'utilisateur. Ne ","anchor":"cas-3-feature-dsactive"},{"id":"v1.0-dev-15-errors-http-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"404 — Not Found","snippet":"L'identifiant demandé (WID ou UUID) n'existe pas en base.\n\n> **Violation de périmètre multi-tenant = 403, pas 404.** Un `CustomerAdmin` (ou tout token scopé) qui essaie d'accéder à une Team, un Networ","anchor":"404-not-found"},{"id":"v1.0-dev-15-errors-http-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"409 — Conflict","snippet":"Une contrainte d'unicité est violée.\n\n**Cas courants :**\n- Email déjà utilisé dans le Customer\n- Invitation `PENDING` déjà existante pour cet email + Customer\n- Subdomain déjà utilisé par un autre Net","anchor":"409-conflict"},{"id":"v1.0-dev-15-errors-http-13","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"429 — Too Many Requests","snippet":"Rate limit dépassé.\n\n**Headers :** `Retry-After: 2` (durée en secondes avant de pouvoir retenter)\n\n**Action :** Respecter le `Retry-After` et implémenter un backoff exponentiel.\n\n```typescript\nconst r","anchor":"429-too-many-requests"},{"id":"v1.0-dev-15-errors-http-14","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"5xx — Erreurs serveur","snippet":"**Causes possibles :**\n- Service downstream injoignable (Keycloak, le service de configuration WakaStart, le service d'authentification WakaStart)\n- Erreur Prisma (contrainte DB inattendue)\n- Timeout ","anchor":"5xx-erreurs-serveur"},{"id":"v1.0-dev-15-errors-http-15","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"Gestion d'erreurs recommandée côté frontend","snippet":"```typescript\nclass ApiError extends Error {\n constructor(\n public readonly status: number,\n public readonly body: { statusCode: number; message: string | string[]; error: string }\n ) {\n su","anchor":"gestion-derreurs-recommande-ct-frontend"},{"id":"v1.0-dev-15-errors-http-16","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"15-errors-http","chapterTitle":"Erreurs — Codes HTTP","heading":"Aller plus loin","snippet":"- [Erreurs métier](16-errors-business) : codes métier custom, messages exacts\n- [Pièges classiques](17-pitfalls) : diagnostic des erreurs fréquentes\n- [Rate limits](11-api-headers-rate-limits) : limit","anchor":"aller-plus-loin"},{"id":"v1.0-dev-16-errors-business-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"16-errors-business","chapterTitle":"Erreurs — Codes métier","heading":"Messages stricts (testables programmatiquement)","snippet":"Certains `message` ont une valeur exacte et stable :\n\n| Message | Status | Signification |\n|---------|--------|---------------|\n| `\"Token enrichi manquant ou invalide\"` | 401 | wakaToken absent ou inv","anchor":"messages-stricts-testables-programmatiquement"},{"id":"v1.0-dev-16-errors-business-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"16-errors-business","chapterTitle":"Erreurs — Codes métier","heading":"Erreurs d'invitation — traitement exhaustif","snippet":"```typescript\n// Gérer les 4 états d'erreur d'une invitation\nasync function loadInvitation(token: string) {\n const res = await fetch(`/api/proxy/invitations/verify/${token}`);\n const { valid, invita","anchor":"erreurs-dinvitation-traitement-exhaustif"},{"id":"v1.0-dev-16-errors-business-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"16-errors-business","chapterTitle":"Erreurs — Codes métier","heading":"Erreurs de droits — messages structurés","snippet":"Les erreurs `403` liées aux droits contiennent des informations structurées dans `message` :\n\n```typescript\n// Extraire le niveau requis vs niveau actuel d'un 403\nfunction parseAdminLevelError(message","anchor":"erreurs-de-droits-messages-structurs"},{"id":"v1.0-dev-16-errors-business-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"16-errors-business","chapterTitle":"Erreurs — Codes métier","heading":"Codes de rate limit par endpoint","snippet":"Certains endpoints ont des messages de rate limit spécifiques qui permettent d'identifier l'endpoint concerné :\n\n```typescript\n// Pattern de détection rate limit\nfunction isRateLimitError(status: numb","anchor":"codes-de-rate-limit-par-endpoint"},{"id":"v1.0-dev-16-errors-business-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"16-errors-business","chapterTitle":"Erreurs — Codes métier","heading":"Erreurs de validation — parsing","snippet":"Pour les `400` avec tableau de messages, construire une map de champs en erreur :\n\n```typescript\ninterface ValidationErrors {\n [field: string]: string[];\n}\n\nfunction parseValidationErrors(\n messages","anchor":"erreurs-de-validation-parsing"},{"id":"v1.0-dev-16-errors-business-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"16-errors-business","chapterTitle":"Erreurs — Codes métier","heading":"Erreurs de conflit (409) — stratégies","snippet":"```typescript\ntry {\n await createInvitation(dto);\n toast.success(\"Invitation envoyée\");\n} catch (err) {\n if (err instanceof ApiError && err.isConflict) {\n const msg = err.body.message as string;","anchor":"erreurs-de-conflit-409-stratgies"},{"id":"v1.0-dev-16-errors-business-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"16-errors-business","chapterTitle":"Erreurs — Codes métier","heading":"Aller plus loin","snippet":"- [Erreurs HTTP](15-errors-http) : codes 400-5xx complets\n- [Invitations — Vérification](19-invitations-verify-accept) : traitement des `valid: false`\n- [Pièges classiques](17-pitfalls) : diagnostic d","anchor":"aller-plus-loin"},{"id":"v1.0-dev-18-invitations-create-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"18-invitations-create","chapterTitle":"API Invitations — Création","heading":"Pré-requis","snippet":"1. **Feature `invitation` activée** en cascade (App ∧ Network ∧ Customer)\n2. **Droit `invitations.create`** sur le token ou la clé API — ce droit est un `AppRight` accordé via le(s) profil(s) assigné(","anchor":"pr-requis"},{"id":"v1.0-dev-18-invitations-create-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"18-invitations-create","chapterTitle":"API Invitations — Création","heading":"Cycle de vie d'une invitation","snippet":"```mermaid\nstateDiagram-v2\n [*] --> PENDING : création\n PENDING --> ACCEPTED : acceptation\n PENDING --> EXPIRED : expiration (10 j)\n PENDING --> CANCELLED : révocation\n ACCEPTED --> [*]\n EXPIRED","anchor":"cycle-de-vie-dune-invitation"},{"id":"v1.0-dev-18-invitations-create-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"18-invitations-create","chapterTitle":"API Invitations — Création","heading":"Flux d'invitation complet","snippet":"```mermaid\nsequenceDiagram\n participant App as Votre WakaApp\n participant WS as WakaStart\n participant Invité as Invité\n\n App->>WS: POST /api/invitations\n WS-->>App: 201 { id, token, ... }\n WS->","anchor":"flux-dinvitation-complet"},{"id":"v1.0-dev-18-invitations-create-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"18-invitations-create","chapterTitle":"API Invitations — Création","heading":"Endpoint — Créer une invitation","snippet":"```http\nPOST /api/invitations\nAuthorization: Bearer \nContent-Type: application/json\n\n{\n \"customerId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"invitedEmail\": \"alice@acme.com\",\n \"invited","anchor":"endpoint-crer-une-invitation"},{"id":"v1.0-dev-18-invitations-create-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"18-invitations-create","chapterTitle":"API Invitations — Création","heading":"Endpoints de gestion","snippet":"","anchor":"endpoints-de-gestion"},{"id":"v1.0-dev-18-invitations-create-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"18-invitations-create","chapterTitle":"API Invitations — Création","heading":"Lister les invitations","snippet":"```http\nGET /api/invitations/sent # Par l'utilisateur courant\nGET /api/invitations/sent/app/:appId # Filtrées par App\nGET /api/invitations/by-customer/:customerI","anchor":"lister-les-invitations"},{"id":"v1.0-dev-18-invitations-create-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"18-invitations-create","chapterTitle":"API Invitations — Création","heading":"Renvoyer une invitation","snippet":"```http\nPOST /api/invitations/:id/resend\n```\n\nGénère un nouveau token, réinitialise `expiresAt` à +10 jours, renvoie l'email. L'ancien token est immédiatement invalide.\n\nUtilisable sur les invitations","anchor":"renvoyer-une-invitation"},{"id":"v1.0-dev-18-invitations-create-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"18-invitations-create","chapterTitle":"API Invitations — Création","heading":"Révoquer une invitation","snippet":"```http\nDELETE /api/invitations/:id\n```\n\nPasse l'invitation en `CANCELLED`. Réponse `200 OK`. Droit requis : `invitations.revoke`.\n\n---","anchor":"rvoquer-une-invitation"},{"id":"v1.0-dev-18-invitations-create-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"18-invitations-create","chapterTitle":"API Invitations — Création","heading":"Exemple curl","snippet":"```bash\n# Créer l'invitation depuis votre backend\ncurl -X POST https://api.wakastart.app/api/invitations \\\n -H \"x-api-key: sk_live_yourkey\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"cust","anchor":"exemple-curl"},{"id":"v1.0-dev-18-invitations-create-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"18-invitations-create","chapterTitle":"API Invitations — Création","heading":"Bonnes pratiques","snippet":"- **Idempotence côté création :** si un appel échoue après création (réseau), retenter lèvera un `409 Conflict` — c'est sûr, l'invitation existante est toujours valide.\n- **Ne jamais logger le token d","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-18-invitations-create-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"18-invitations-create","chapterTitle":"API Invitations — Création","heading":"Aller plus loin","snippet":"- [Invitations — Vérification & Acceptation](19-invitations-verify-accept) : `verify`, `accept`, lifecycle complet\n- [Feature flags](09-access-control-features) : activation de la feature `invitations","anchor":"aller-plus-loin"},{"id":"v1.0-dev-19-invitations-verify-accept-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"19-invitations-verify-accept","chapterTitle":"API Invitations — Vérification & Acceptation","heading":"Endpoint — Vérifier un token (PUBLIC)","snippet":"À appeler depuis votre page d'acceptation au chargement, avant d'afficher le formulaire.\n\n```http\nGET /api/invitations/verify/{token}\n```\n\n**Auth :** Aucune — endpoint public. **Throttle :** 10 req/mi","anchor":"endpoint-vrifier-un-token-public"},{"id":"v1.0-dev-19-invitations-verify-accept-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"19-invitations-verify-accept","chapterTitle":"API Invitations — Vérification & Acceptation","heading":"Pattern React — Page d'acceptation","snippet":"```typescript\n// app/accept-invitation/[token]/page.tsx\nasync function AcceptInvitationPage({ params }: { params: { token: string } }) {\n // Appel DIRECT à la public-api : le contrôleur BFF (/api/pro","anchor":"pattern-react-page-dacceptation"},{"id":"v1.0-dev-19-invitations-verify-accept-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"19-invitations-verify-accept","chapterTitle":"API Invitations — Vérification & Acceptation","heading":"Endpoint — Accepter une invitation (PUBLIC)","snippet":"```http\nPOST /api/invitations/accept/{token}\nContent-Type: application/json\n\n{ \"password\": \"MotDePasse2026!\" }\n```\n\n**Auth :** Aucune — endpoint public. **Throttle :** 5 req/min/IP.\n\n**Réponse 201 :**","anchor":"endpoint-accepter-une-invitation-public"},{"id":"v1.0-dev-19-invitations-verify-accept-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"19-invitations-verify-accept","chapterTitle":"API Invitations — Vérification & Acceptation","heading":"Exemple curl — flux complet","snippet":"```bash\n# 1. Votre backend crée l'invitation\ncurl -X POST https://api.wakastart.app/api/invitations \\\n -H \"x-api-key: sk_live_yourkey\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"customerI","anchor":"exemple-curl-flux-complet"},{"id":"v1.0-dev-19-invitations-verify-accept-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"19-invitations-verify-accept","chapterTitle":"API Invitations — Vérification & Acceptation","heading":"Bonnes pratiques","snippet":"- **Toujours appeler `verify` au mount** avant d'afficher le formulaire — évite à l'invité de saisir un mot de passe pour rien.\n- **Gérer les 4 états d'erreur** avec des messages explicites adaptés.","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-19-invitations-verify-accept-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"19-invitations-verify-accept","chapterTitle":"API Invitations — Vérification & Acceptation","heading":"Pièges classiques","snippet":"- **Appeler `accept` deux fois** : après acceptation, le token est invalidé. Le deuxième appel retourne `400 Cette invitation a déjà été acceptée`.\n- **Oublier le `verify` initial** : l'invité remplit","anchor":"piges-classiques"},{"id":"v1.0-dev-19-invitations-verify-accept-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"19-invitations-verify-accept","chapterTitle":"API Invitations — Vérification & Acceptation","heading":"Aller plus loin","snippet":"- [Invitations — Création](18-invitations-create) : endpoint POST, pré-requis, cycle de vie\n- [Erreurs métier](16-errors-business) : traitement des messages `valid: false`\n- [Contrôle d'accès](07-acce","anchor":"aller-plus-loin"},{"id":"v1.0-dev-20-mcp-server-overview-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"Pourquoi cette intégration","snippet":"Plutôt que de jongler entre cette documentation et votre IDE, vous pouvez configurer Claude Code pour qu'il interroge directement le MCP et obtienne : la liste des endpoints disponibles, le détail des","anchor":"pourquoi-cette-intgration"},{"id":"v1.0-dev-20-mcp-server-overview-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"5 Tools disponibles","snippet":"","anchor":"5-tools-disponibles"},{"id":"v1.0-dev-20-mcp-server-overview-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"1. `list_endpoints`","snippet":"Liste tous les endpoints `/api/*` avec méthode HTTP, route, droit requis et description.\n\n```bash\ncurl -X POST https://docs.wakastart.app/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\n ","anchor":"1-list_endpoints"},{"id":"v1.0-dev-20-mcp-server-overview-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"2. `get_endpoint_spec`","snippet":"Détail complet d'un endpoint : DTO request/response, codes HTTP, droit requis, exemples.\n\n```bash\ncurl -X POST https://docs.wakastart.app/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\n ","anchor":"2-get_endpoint_spec"},{"id":"v1.0-dev-20-mcp-server-overview-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"3. `search_docs`","snippet":"Recherche full-text dans les chapitres de documentation Markdown du site.\n\n```bash\ncurl -X POST https://docs.wakastart.app/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"jsonrpc\": \"2.0","anchor":"3-search_docs"},{"id":"v1.0-dev-20-mcp-server-overview-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"4. `get_auth_flow`","snippet":"Résumé structuré du flow d'authentification.\n\n**Paramètres :**\n- `format` : `summary` | `full` (défaut: `full`)\n- `context` : `frontend` | `backend` | `mobile`\n\n---","anchor":"4-get_auth_flow"},{"id":"v1.0-dev-20-mcp-server-overview-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"5. `get_error_code`","snippet":"Détail d'un code d'erreur HTTP ou métier Wakastart.\n\n**Codes reconnus :** `401`, `403`, `404`, `409`, `429`, `5xx`, `BOLA`, `TOKEN_EXPIRED`, `VULN-002`…\n\n---","anchor":"5-get_error_code"},{"id":"v1.0-dev-20-mcp-server-overview-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"Resources disponibles","snippet":"```bash\n# Handshake MCP (obligatoire avant toute interaction)\ncurl -X POST https://docs.wakastart.app/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 0,\n \"","anchor":"resources-disponibles"},{"id":"v1.0-dev-20-mcp-server-overview-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"Caractéristiques techniques","snippet":"| Aspect | Valeur |\n|--------|--------|\n| **Transport** | HTTP (JSON-RPC 2.0) |\n| **Authentification** | Aucune (documentation publique) |\n| **Rate limit** | Aucune limitation de débit actuellement |\n","anchor":"caractristiques-techniques"},{"id":"v1.0-dev-20-mcp-server-overview-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"URLs par environnement","snippet":"| Environnement | URL MCP |\n|---------------|---------|\n| Dev local | `http://localhost/api/mcp` |\n| Staging | `https://docs-staging.wakastart.app/api/mcp` |\n| Production | `https://docs.wakastart.app","anchor":"urls-par-environnement"},{"id":"v1.0-dev-20-mcp-server-overview-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"Swagger UI","snippet":"La spec OpenAPI est également disponible via l'interface interactive de ce site :\n\n```\nhttps://docs.wakastart.app/v1.0/dev/api-reference\n```\n\n**JSON brut (pour import dans Postman, Insomnia, etc.) :**","anchor":"swagger-ui"},{"id":"v1.0-dev-20-mcp-server-overview-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"Bonnes pratiques","snippet":"- Utilisez `list_endpoints` + `get_endpoint_spec` en début de sprint pour découvrir les nouvelles routes.\n- Le MCP est read-only — il ne peut pas modifier la plateforme.\n- En CI/CD, ne pas inclure `.m","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-20-mcp-server-overview-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Vue d'ensemble","heading":"Aller plus loin","snippet":"- [Configuration Claude Code](21-mcp-server-claude-code-setup) : `.mcp.json`, exemples et utilisation avancée\n- [Référence des endpoints](14-endpoint-reference) : tableau statique de toutes les routes","anchor":"aller-plus-loin"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Configuration `.mcp.json`","snippet":"Créez un fichier `.mcp.json` à la racine de votre projet WakaApp :\n\n```json\n{\n \"mcpServers\": {\n \"wakastart-docs\": {\n \"url\": \"http://localhost/api/mcp\",\n \"transport\": \"http\"\n }\n }\n}\n`","anchor":"configuration-mcpjson"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Questions que vous pouvez poser à Claude","snippet":"Une fois configuré, interrogez directement depuis Claude Code :","anchor":"questions-que-vous-pouvez-poser-claude"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Via `list_endpoints`","snippet":"- *\"Montre-moi tous les endpoints d'authentification\"*\n- *\"Quels endpoints acceptent des POST ?\"*\n- *\"Liste tous les endpoints d'invitations avec leurs droits requis\"*","anchor":"via-list_endpoints"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Via `get_endpoint_spec`","snippet":"- *\"Quel est le body attendu pour POST /api/invitations ?\"*\n- *\"Quels codes d'erreur peut retourner DELETE /api/invitations/:id ?\"*\n- *\"Génère un exemple curl pour POST /api/auth/enrich\"*","anchor":"via-get_endpoint_spec"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Via `search_docs`","snippet":"- *\"Comment fonctionne le PKCE dans Wakastart ?\"*\n- *\"Qu'est-ce qu'un AppRight ?\"*\n- *\"Comment configurer le rate limiting côté Wakapp ?\"*","anchor":"via-search_docs"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Via `get_auth_flow`","snippet":"- *\"Explique-moi le flow d'auth Wakastart pour une app frontend\"*\n- *\"Comment fonctionne l'auth M2M avec une API key ?\"*","anchor":"via-get_auth_flow"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Via `get_error_code`","snippet":"- *\"Pourquoi est-ce que j'obtiens un 401 ?\"*\n- *\"Qu'est-ce que BOLA ?\"*\n- *\"Quand est-ce que l'API retourne un 409 ?\"*\n\n---","anchor":"via-get_error_code"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Vérification du serveur","snippet":"Testez que le serveur répond :\n\n```bash\n# Handshake\ncurl -X POST http://localhost/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":0,\"method\":\"initialize\",\"params\":{\"proto","anchor":"vrification-du-serveur"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Exemple de session Claude Code","snippet":"Une fois `.mcp.json` configuré :\n\n```\nVous : \"Génère le code TypeScript pour appeler POST /api/invitations\"\n\nClaude : [Appelle list_endpoints avec tag=\"Invitations\"]\n [Appelle get_endpoint_spe","anchor":"exemple-de-session-claude-code"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Utilisation avec `resources/read`","snippet":"Pour lire un chapitre complet de documentation dans Claude :\n\n```bash\ncurl -X POST https://docs.wakastart.app/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": ","anchor":"utilisation-avec-resourcesread"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Bonnes pratiques","snippet":"- Utilisez `list_endpoints` + `get_endpoint_spec` en début de sprint.\n- Le MCP est read-only — aucun risque de modifier la plateforme.\n- En CI/CD, **ne pas inclure `.mcp.json`** dans le container de p","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Configuration Claude Code","heading":"Aller plus loin","snippet":"- [Vue d'ensemble du MCP](20-mcp-server-overview) : tools, resources, caractéristiques techniques\n- [Référence des endpoints](14-endpoint-reference) : tableau statique de toutes les routes","anchor":"aller-plus-loin"},{"id":"v1.0-dev-22-platform-overview-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"22-platform-overview","chapterTitle":"Vue d'ensemble de la plateforme","heading":"📍 Où accéder à la partie Infra dans l'UI","snippet":"Menu **Applications** → clique sur ton app → l'icône **🚀 fusée verte** sur la carte de l'app ouvre l'espace **Infra / Hébergement** dédié à cette app.\n\nC'est le point d'entrée pour toutes les fonctio","anchor":"-o-accder-la-partie-infra-dans-lui"},{"id":"v1.0-dev-22-platform-overview-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"22-platform-overview","chapterTitle":"Vue d'ensemble de la plateforme","heading":"Le mantra à retenir","snippet":"> *Tu déclares **ce que** ton app contient.*\n> *Wakastart la **build**, l'**héberge** et l'**exécute**.*","anchor":"le-mantra-retenir"},{"id":"v1.0-dev-23-app-hierarchy-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"23-app-hierarchy","chapterTitle":"Hiérarchie App → Environnement → Instances","heading":"Pourquoi cette séparation Architecture vs Environnement ?","snippet":"L'**Architecture** décrit ton app **une fois** : \"j'ai un backend Node.js, une base PostgreSQL, un bucket S3\".\n\nLes **Environnements** instancient cette architecture **autant de fois que tu veux** : d","anchor":"pourquoi-cette-sparation-architecture-vs-environnement-"},{"id":"v1.0-dev-36-architecture-json-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Pourquoi l'utiliser ?","snippet":"- **Démarrer vite.** Plus besoin de cliquer 30 fois pour créer 5 services, 1 base et 2 URLs : un seul fichier JSON et c'est importé.\n- **Cloner une app.** Exportez une app qui marche, importez-la sur ","anchor":"pourquoi-lutiliser-"},{"id":"v1.0-dev-36-architecture-json-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"En deux mots","snippet":"Le JSON décrit **uniquement votre architecture** : repos, services, bases, stockage, URLs, environnements. Pas vos secrets, pas vos credentials, pas vos volumes de données.\n\nUne fois importé, votre ap","anchor":"en-deux-mots"},{"id":"v1.0-dev-36-architecture-json-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Importer une architecture","snippet":"","anchor":"importer-une-architecture"},{"id":"v1.0-dev-36-architecture-json-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Pré-requis","snippet":"- Vous avez **créé l'app cible** (peu importe comment).\n- L'app cible est **vierge côté architecture** : aucun service, aucune base, aucun bucket, aucune URL n'a encore été ajouté manuellement.\n\n> Si ","anchor":"pr-requis"},{"id":"v1.0-dev-36-architecture-json-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Procédure","snippet":"1. Ouvrez votre app → **Architecture**\n2. Cliquez sur **Importer** (en haut à droite, à côté de **Exporter**)\n3. **Étape 1 — Coller + Valider**\n - Collez votre JSON dans le champ texte\n - Cliquez ","anchor":"procdure"},{"id":"v1.0-dev-36-architecture-json-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Exporter une architecture","snippet":"","anchor":"exporter-une-architecture"},{"id":"v1.0-dev-36-architecture-json-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Quand ?","snippet":"- Vous avez une app qui marche bien et vous voulez la **cloner** sur une autre app cible (autre WakaStart, autre environnement).\n- Vous voulez **archiver** la description infra de votre app pour la ve","anchor":"quand-"},{"id":"v1.0-dev-36-architecture-json-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Procédure","snippet":"1. Ouvrez votre app → **Architecture**\n2. Cliquez sur **Exporter** → un dialog s'ouvre avec un résumé des transformations appliquées\n3. Au choix :\n - **Copier** le JSON dans le presse-papier\n - **","anchor":"procdure"},{"id":"v1.0-dev-36-architecture-json-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Ce qui est exporté et ce qui ne l'est pas","snippet":"| Inclus | Exclu |\n|---|---|\n| Métadonnées d'app (`name`, `shortname`) | Identifiants techniques (regénérés sur l'app cible) |\n| Repos (en lecture seule) | Crédentials Git |\n| Services + variables d'e","anchor":"ce-qui-est-export-et-ce-qui-ne-lest-pas"},{"id":"v1.0-dev-36-architecture-json-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Le format JSON — référence pratique","snippet":"","anchor":"le-format-json-rfrence-pratique"},{"id":"v1.0-dev-36-architecture-json-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Squelette minimal","snippet":"```json\n{\n \"version\": \"1.0\",\n \"kind\": \"wakastart-app-architecture\",\n \"app\": {\n \"name\": \"Mon Application\",\n \"shortname\": \"monapp\"\n }\n}\n```\n\nLe bloc `app` et l'entête `version` + `kind` sont l","anchor":"squelette-minimal"},{"id":"v1.0-dev-36-architecture-json-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Sections disponibles","snippet":"| Section | Type | Quand l'utiliser |\n|---|---|---|\n| `app` | obligatoire | Métadonnées (name, shortname) |\n| `repos` | recommandé | Vos repos GitHub à brancher |\n| `serviceDefinitions` | recommandé |","anchor":"sections-disponibles"},{"id":"v1.0-dev-36-architecture-json-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Bloc `repos`","snippet":"Vos repos GitHub à brancher à votre app. **Deux modes** au choix selon que le repo existe déjà ou non :\n\n#### Mode 1 — repo géré (`isManaged: true`) : WakaStart le crée pour vous\n\n```json\n\"repos\": [\n ","anchor":"bloc-repos"},{"id":"v1.0-dev-36-architecture-json-13","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Bloc `serviceDefinitions`","snippet":"```json\n\"serviceDefinitions\": [\n {\n \"ref\": \"api\",\n \"name\": \"API Backend\",\n \"shortname\": \"api\",\n \"repoRef\": \"main-repo\",\n \"rootDirectory\": \"./backend\",\n \"dockerfilePath\": \"Dockerfile","anchor":"bloc-servicedefinitions"},{"id":"v1.0-dev-36-architecture-json-14","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Bloc `databaseDefinitions`","snippet":"```json\n\"databaseDefinitions\": [\n {\n \"ref\": \"pg\",\n \"name\": \"PostgreSQL principale\",\n \"shortname\": \"pg\",\n \"engineType\": \"POSTGRESQL\",\n \"defaultMode\": \"IN_CLUSTER\",\n \"defaultPlan\": \"e","anchor":"bloc-databasedefinitions"},{"id":"v1.0-dev-36-architecture-json-15","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Bloc `storageBucketDefinitions`","snippet":"```json\n\"storageBucketDefinitions\": [\n {\n \"ref\": \"uploads\",\n \"name\": \"Uploads utilisateurs\",\n \"shortname\": \"uploads\",\n \"defaultRegion\": \"gra\",\n \"defaultStorageClass\": \"STANDARD\",\n \"","anchor":"bloc-storagebucketdefinitions"},{"id":"v1.0-dev-36-architecture-json-16","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Blocs `appUrls` et `appRoutes`","snippet":"```json\n\"appUrls\": [\n { \"ref\": \"api-url\", \"subdomain\": \"api\", \"domainRef\": null },\n { \"ref\": \"app-url\", \"subdomain\": \"app\", \"domainRef\": null }\n],\n\"appRoutes\": [\n { \"serviceRef\": \"api\", \"urlRef\":","anchor":"blocs-appurls-et-approutes"},{"id":"v1.0-dev-36-architecture-json-17","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Blocs `appApexUrls` et `appUrlRedirects` (domaines `CUSTOM` uniquement)","snippet":"Ces deux blocs décrivent les capacités liées à un **domaine `CUSTOM`** : exposer l'app à la racine d'un domaine (apex) et rediriger une URL vers une autre au sein de l'app (voir [URLs et routing](./ro","anchor":"blocs-appapexurls-et-appurlredirects-domaines-custom-uniquement"},{"id":"v1.0-dev-36-architecture-json-18","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Bloc `environments` (optionnel)","snippet":"```json\n\"environments\": [\n { \"env\": \"dev\", \"shortname\": \"dev\", \"slug\": \"dev\", \"urlPrefix\": \"dev\" },\n { \"env\": \"staging\", \"shortname\": \"stg\", \"slug\": \"staging\", \"urlPrefix\": \"staging\" },\n { ","anchor":"bloc-environments-optionnel"},{"id":"v1.0-dev-36-architecture-json-19","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Trois exemples concrets","snippet":"","anchor":"trois-exemples-concrets"},{"id":"v1.0-dev-36-architecture-json-20","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"1. App monolithique (back + front)","snippet":"```json\n{\n \"version\": \"1.0\",\n \"kind\": \"wakastart-app-architecture\",\n \"app\": { \"name\": \"Hello World\", \"shortname\": \"hello\" },\n \"repos\": [\n {\n \"ref\": \"main\",\n \"name\": \"hello-world\",\n ","anchor":"1-app-monolithique-back-front"},{"id":"v1.0-dev-36-architecture-json-21","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"2. App avec base de données et stockage","snippet":"Ajoutez les blocs `databaseDefinitions` + `storageBucketDefinitions` au précédent, et déclarez les variables que votre back attend :\n\n```json\n\"databaseDefinitions\": [\n {\n \"ref\": \"pg\", \"name\": \"Pos","anchor":"2-app-avec-base-de-donnes-et-stockage"},{"id":"v1.0-dev-36-architecture-json-22","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"3. App multi-services avec environnements préconfigurés","snippet":"Si vous voulez créer les environnements en un seul import :\n\n```json\n\"environments\": [\n { \"env\": \"dev\", \"shortname\": \"dev\", \"slug\": \"dev\", \"urlPrefix\": \"dev\" },\n { \"env\": \"prod\", \"shortname\": \"prd","anchor":"3-app-multi-services-avec-environnements-prconfigurs"},{"id":"v1.0-dev-36-architecture-json-23","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Bonnes pratiques","snippet":"- **Un seul `shortname` par bloc** : un service `api` et une DB `api` peuvent coexister, mais deux services avec `shortname: \"api\"` non.\n- **Cohérence des `varRequirements`** : déclarez **toutes** les","anchor":"bonnes-pratiques"},{"id":"v1.0-dev-36-architecture-json-24","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Erreurs courantes","snippet":"| Symptôme | Cause | Remède |\n|---|---|---|\n| Bouton **Importer** grisé | L'app cible contient déjà des ressources | Créez une **app vierge** (jamais éditée) ou supprimez les ressources |\n| Étape 1 af","anchor":"erreurs-courantes"},{"id":"v1.0-dev-36-architecture-json-25","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Utiliser une IA pour générer le JSON","snippet":"Le format est volontairement **prévisible** et **strict** pour qu'un assistant comme Claude, ChatGPT, Cursor, etc. produise un JSON valide du premier coup.","anchor":"utiliser-une-ia-pour-gnrer-le-json"},{"id":"v1.0-dev-36-architecture-json-26","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Prompt type","snippet":"> Voici la description de mon projet : je veux une API Node.js qui se connecte à une PostgreSQL et écrit des fichiers dans un bucket S3, plus un frontend Next.js. Je veux que WakaStart me crée un nouv","anchor":"prompt-type"},{"id":"v1.0-dev-36-architecture-json-27","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Conseils","snippet":"- Demandez à l'IA de **valider le JSON** avant de vous le rendre (clé d'entête `\"version\": \"1.0\"`, `\"kind\": \"wakastart-app-architecture\"`).\n- Si l'étape **Valider** affiche des erreurs, **renvoyez-les","anchor":"conseils"},{"id":"v1.0-dev-36-architecture-json-28","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"36-architecture-json","chapterTitle":"Décrire son architecture en JSON","heading":"Aller plus loin","snippet":"- [Repositories](./repositories)\n- [Services](./services)\n- [Bases, stockage, routing](./databases-storage)\n- [URLs et routing](./routing-urls)\n- [Variables et secrets](./vars-secrets)\n- [Environnemen","anchor":"aller-plus-loin"},{"id":"v1.0-dev-24-repositories-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"24-repositories","chapterTitle":"Repository (dépôt Git)","heading":"À quoi ça sert un repo dans Wakastart ?","snippet":"Un repo n'est **pas** un service à lui tout seul. Il fournit le code source qui sera ensuite :\n\n1. Lu pour faire un **Build** (transformer le code en image Docker)\n2. Utilisé pour ses branches/tags (r","anchor":"-quoi-a-sert-un-repo-dans-wakastart-"},{"id":"v1.0-dev-25-services-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"25-services","chapterTitle":"Service — composant exécutable","heading":"ServiceDefinition (niveau Architecture)","snippet":"C'est la **définition** générique du service. Tu décris :\n\n| Champ | Exemple | Explication |\n|-------|---------|-------------|\n| **Rôle** | `BACK` | Backend, frontend, API, worker… |\n| **Protocol** | ","anchor":"servicedefinition-niveau-architecture"},{"id":"v1.0-dev-25-services-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"25-services","chapterTitle":"Service — composant exécutable","heading":"Configurer le build : rootDirectory, dockerfilePath, buildContext","snippet":"Trois paramètres ServiceDefinition pilotent l'étape `docker build` :\n\n| Champ | Rôle | Relatif à |\n|-------|------|-----------|\n| **rootDirectory** | Répertoire de base utilisé comme \"racine virtuelle","anchor":"configurer-le-build-rootdirectory-dockerfilepath-buildcontext"},{"id":"v1.0-dev-25-services-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"25-services","chapterTitle":"Service — composant exécutable","heading":"Cas 1 — Repo simple, Dockerfile à la racine","snippet":"```\nle BFF WakaStart/\n├── Dockerfile\n├── package.json\n└── src/\n```\n\n| Champ | Valeur |\n|-------|--------|\n| `rootDirectory` | `./` |\n| `dockerfilePath` | `Dockerfile` |\n| `buildContext` | `.` |\n\nÉquiv","anchor":"cas-1-repo-simple-dockerfile-la-racine"},{"id":"v1.0-dev-25-services-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"25-services","chapterTitle":"Service — composant exécutable","heading":"Cas 2 — Monorepo, projet dans un sous-dossier","snippet":"```\nle BFF WakaStart/\n├── apps/\n│ ├── backend/\n│ │ ├── Dockerfile\n│ │ ├── package.json\n│ │ └── src/\n│ └── worker/\n└── packages/\n```\n\nTu veux builder uniquement `apps/backend` et limite","anchor":"cas-2-monorepo-projet-dans-un-sous-dossier"},{"id":"v1.0-dev-25-services-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"25-services","chapterTitle":"Service — composant exécutable","heading":"Cas 3 — Monorepo avec lockfile partagé (pnpm/yarn workspaces, turbo…)","snippet":"Ton service est dans `apps/backend/` mais a besoin du `pnpm-lock.yaml` racine et des packages partagés `packages/*` pour s'installer :\n\n```\nle BFF WakaStart/\n├── pnpm-lock.yaml ← lockfile raci","anchor":"cas-3-monorepo-avec-lockfile-partag-pnpmyarn-workspaces-turbo"},{"id":"v1.0-dev-25-services-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"25-services","chapterTitle":"Service — composant exécutable","heading":"Règles pratiques","snippet":"- **Plus le `buildContext` est petit, plus le build est rapide** (Docker envoie moins de fichiers au daemon). Si ton service est autonome dans un sous-dossier, choisis le Cas 2.\n- **Si ton Dockerfile ","anchor":"rgles-pratiques"},{"id":"v1.0-dev-25-services-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"25-services","chapterTitle":"Service — composant exécutable","heading":"ServiceInstance (niveau Environnement)","snippet":"C'est l'**instance** réelle d'un service dans un environnement précis (ex: backend en dev, backend en prod). Elle hérite des valeurs par défaut de la Definition mais peut les overrider :\n\n```\nServiceD","anchor":"serviceinstance-niveau-environnement"},{"id":"v1.0-dev-26-builds-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Le pipeline d'un Build","snippet":"```\nRepository (code source)\n ↓\n git checkout \n ↓\n docker build (Dockerfile)\n ↓\n Image Docker dans le registry privé Wakastart\n ↓\n Disponible pour déploi","anchor":"le-pipeline-dun-build"},{"id":"v1.0-dev-26-builds-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Statuts d'un build","snippet":"| Statut | Signification |\n|--------|---------------|\n| `PENDING` | En attente d'exécution |\n| `BUILDING` | Docker build en cours |\n| `PUSHING` | Image construite, en cours d'upload vers le registry |","anchor":"statuts-dun-build"},{"id":"v1.0-dev-26-builds-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Comment déclencher un build","snippet":"| Trigger | Quand |\n|---------|-------|\n| `MANUAL` | Tu cliques \"Build\" dans l'UI en choisissant une branche/tag/commit |\n| `GIT_PUSH` | 🚧 *Coming soon* — déclenchera automatiquement un build sur pus","anchor":"comment-dclencher-un-build"},{"id":"v1.0-dev-26-builds-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Nom des images","snippet":"Chaque build produit une image au nom unique. La date et l'heure sont en UTC.\n\n| Type de build | Nom de l'image | Exemple |\n|---------------|----------------|---------|\n| Branche | `-AAAAMMJJ","anchor":"nom-des-images"},{"id":"v1.0-dev-26-builds-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Cache de build","snippet":"Chaque build repart de zéro : la plateforme ne réutilise aucune couche d'un build précédent. Il n'y a plus d'option « Sans cache ».\n\nLe champ `noCache` est encore accepté par l'API, pour ne pas casser","anchor":"cache-de-build"},{"id":"v1.0-dev-26-builds-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Conservation des images (purge automatique)","snippet":"Chaque build réussi laisse une image dans le registre de l'app. Sans purge, ces images s'accumulent. La purge automatique supprime les images des builds les plus anciens, en gardant toujours celles qu","anchor":"conservation-des-images-purge-automatique"},{"id":"v1.0-dev-26-builds-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Activer la purge","snippet":"La purge est **désactivée par défaut**. Elle se règle app par app :\n\n1. Ouvre Infra → **Builds**, carte **Purge automatique des builds**.\n2. Active **Purge automatique**.\n3. Règle **Builds gardés par ","anchor":"activer-la-purge"},{"id":"v1.0-dev-26-builds-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Ce qui est gardé","snippet":"Les builds sont rangés par groupe. Dans chaque groupe, les N plus récents sont gardés (N = le nombre choisi) :\n\n| Type de build | Groupe |\n|---------------|--------|\n| Branche | la branche |\n| Commit ","anchor":"ce-qui-est-gard"},{"id":"v1.0-dev-26-builds-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Ce qui n'est jamais supprimé","snippet":"Même au-delà des N plus récents, une image est toujours gardée si :\n\n- elle tourne dans un environnement de l'app ;\n- elle a été déployée il y a moins de 90 jours, y compris l'image remplacée par ce d","anchor":"ce-qui-nest-jamais-supprim"},{"id":"v1.0-dev-26-builds-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Quand et comment","snippet":"- La purge passe **chaque nuit à 03:30**.\n- Elle supprime **100 images au plus par nuit**, pour toute la plateforme. Une première purge importante peut donc s'étaler sur plusieurs nuits.\n- **Une image","anchor":"quand-et-comment"},{"id":"v1.0-dev-26-builds-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Purge en simulation","snippet":"La plateforme peut faire tourner la purge en simulation. Dans ce cas, **rien n'est supprimé** : la purge calcule seulement les images qui seraient parties. La carte l'indique par un message qui commen","anchor":"purge-en-simulation"},{"id":"v1.0-dev-26-builds-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Badges de la liste des builds","snippet":"| Badge | Signification |\n|-------|---------------|\n| **Déployé · prod, dev** | L'image tourne dans des environnements de ces types |\n| **Conservé** | La purge ne supprimera pas cette image : elle fai","anchor":"badges-de-la-liste-des-builds"},{"id":"v1.0-dev-26-builds-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Quota du registre","snippet":"Un administrateur de la plateforme peut fixer un **quota** de stockage pour une app. Par défaut, il n'y en a pas.","anchor":"quota-du-registre"},{"id":"v1.0-dev-26-builds-13","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"La carte Registre","snippet":"La carte **Registre**, en haut de Infra → **Builds**, affiche :\n\n- le stockage occupé par les images de l'app, et la date du relevé ;\n- s'il y a un quota : le stockage utilisé sur le quota, avec une j","anchor":"la-carte-registre"},{"id":"v1.0-dev-26-builds-14","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Quand le quota est atteint","snippet":"Wakastart refuse de lancer un nouveau build de l'app, qu'il soit lancé depuis la console, par l'API ou automatiquement. Le message est :\n\n```\nQuota du registre atteint : X Go utilisés sur Y Go. Libére","anchor":"quand-le-quota-est-atteint"},{"id":"v1.0-dev-26-builds-15","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Libérer de la place","snippet":"Active la purge automatique (voir ci-dessus). Attention : la place d'une image purgée n'est libérée qu'au **nettoyage hebdomadaire du registre**, le dimanche à 00:00 UTC. D'ici là, le stockage affiché","anchor":"librer-de-la-place"},{"id":"v1.0-dev-26-builds-16","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"26-builds","chapterTitle":"Build — du code à l'image Docker","heading":"Diagnostiquer un build en échec","snippet":"Si un build Wakastart termine en `FAILED`, le premier réflexe est de **reproduire l'erreur localement avec `docker build`**. Le builder Wakastart exécute exactement la même commande que toi en local —","anchor":"diagnostiquer-un-build-en-chec"},{"id":"v1.0-dev-27-databases-storage-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"27-databases-storage","chapterTitle":"Bases de données et stockage","heading":"Base de données (Database)","snippet":"> **C'est quoi ?** Un système qui stocke des données structurées et permet de les requêter. C'est le coeur de la persistance de ton app.\n\nMoteurs disponibles dans Wakastart :\n\n| Engine | Type | Usage ","anchor":"base-de-donnes-database"},{"id":"v1.0-dev-27-databases-storage-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"27-databases-storage","chapterTitle":"Bases de données et stockage","heading":"2 modes : `IN_CLUSTER` vs `MANAGED`","snippet":"| Mode | Où c'est hébergé | Pour |\n|------|------------------|------|\n| **IN_CLUSTER** | Dans le cluster K8s Wakastart, comme un pod | Dev, prototypes, faible volume |\n| **MANAGED** | Sur une infrastr","anchor":"2-modes-in_cluster-vs-managed"},{"id":"v1.0-dev-27-databases-storage-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"27-databases-storage","chapterTitle":"Bases de données et stockage","heading":"Pattern d'usage typique","snippet":"```\nDatabaseDefinition \"primary\"\n├── engineType: POSTGRESQL\n├── defaultMode: IN_CLUSTER\n├── defaultPlan: \"essential\"\n└── defaultVersion: \"15\"\n```","anchor":"pattern-dusage-typique"},{"id":"v1.0-dev-27-databases-storage-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"27-databases-storage","chapterTitle":"Bases de données et stockage","heading":"Stockage (Storage Bucket) — S3","snippet":"> **C'est quoi un bucket S3 ?** Un système de stockage de **fichiers/objets** : images, vidéos, PDF, archives, exports CSV… Tout ce qui n'est pas structuré et n'a pas besoin d'un schéma relationnel.\n\n","anchor":"stockage-storage-bucket-s3"},{"id":"v1.0-dev-27-databases-storage-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"27-databases-storage","chapterTitle":"Bases de données et stockage","heading":"StorageBucketDefinition / StorageBucketInstance","snippet":"Même pattern que les databases : tu définis une fois au niveau Architecture, instancié par environnement.\n\nUne StorageBucketInstance produit pour le code applicatif **6 credentials** :\n\n- `S3_URL` — U","anchor":"storagebucketdefinition-storagebucketinstance"},{"id":"v1.0-dev-28-routing-urls-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"28-routing-urls","chapterTitle":"URLs et routing","heading":"Domaines (App Domain)","snippet":"| Type | Exemple | Source |\n|------|---------|--------|\n| **PLATFORM_MANAGED** | `*.wakastart.app` | Géré par Wakastart, certificats SSL auto, gratuit |\n| **CUSTOM** | `exemple.com` | Tu apportes ton ","anchor":"domaines-app-domain"},{"id":"v1.0-dev-28-routing-urls-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"28-routing-urls","chapterTitle":"URLs et routing","heading":"App URL = sous-domaine + (préfixe d'env) + domaine","snippet":"Le pattern d'URL Wakastart insère le slug de l'environnement comme préfixe entre le sous-domaine et le domaine racine — sauf pour la prod, qui n'a pas de préfixe.\n\n```\nprod → sous-domaine \"app\" + ","anchor":"app-url-sous-domaine-prfixe-denv-domaine"},{"id":"v1.0-dev-28-routing-urls-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"28-routing-urls","chapterTitle":"URLs et routing","heading":"Exposer une app à la racine d'un domaine (apex)","snippet":"Par défaut, une URL exige toujours un sous-domaine (`app`, `api`…). Mais si tu apportes un domaine **CUSTOM** (`monsupersite.com`), tu peux vouloir exposer ton app **directement à la racine** — sur `m","anchor":"exposer-une-app-la-racine-dun-domaine-apex"},{"id":"v1.0-dev-28-routing-urls-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"28-routing-urls","chapterTitle":"URLs et routing","heading":"AppApexUrl (Architecture) → AppApexUrlInstance (par environnement)","snippet":"Comme le reste de l'architecture, l'apex se déclare **une fois** puis s'instancie **par environnement** :\n\n| Niveau | Ressource | Ce que tu décris |\n|--------|-----------|------------------|\n| **Archi","anchor":"appapexurl-architecture-appapexurlinstance-par-environnement"},{"id":"v1.0-dev-28-routing-urls-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"28-routing-urls","chapterTitle":"URLs et routing","heading":"DNS : toujours un enregistrement `A`/`AAAA`, jamais un `CNAME`","snippet":"Un `CNAME` à la racine d'une zone est structurellement invalide (RFC 1034/1912). Pour tout hostname apex, Wakastart force donc automatiquement un enregistrement `A`/`AAAA`, quel que soit le provider —","anchor":"dns-toujours-un-enregistrement-aaaaa-jamais-un-cname"},{"id":"v1.0-dev-28-routing-urls-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"28-routing-urls","chapterTitle":"URLs et routing","heading":"Avertissement obligatoire à l'instanciation","snippet":"Exposer un domaine à sa racine écrit un enregistrement DNS à la racine **sans sous-domaine**. Or Wakastart **ne vérifie pas** ce qui résout déjà sur ce domaine : un site tiers déjà en production dessu","anchor":"avertissement-obligatoire-linstanciation"},{"id":"v1.0-dev-28-routing-urls-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"28-routing-urls","chapterTitle":"URLs et routing","heading":"HttpRoute = routing interne d'une URL","snippet":"À une URL on attache une **HttpRoute** qui dit \"envoie tout `/api/*` vers le ServiceInstance backend, tout `/` vers le ServiceInstance frontend\". C'est du routage applicatif (équivalent d'un reverse p","anchor":"httproute-routing-interne-dune-url"},{"id":"v1.0-dev-28-routing-urls-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"28-routing-urls","chapterTitle":"URLs et routing","heading":"URL front officielle (Primary Front URL)","snippet":"Une app peut avoir plusieurs routes (`AppRoute`) pointant vers plusieurs services de rôle `FRONT` (front web, front mobile packagé en PWA, etc.). Rien ne distingue par défaut laquelle est \"la\" URL fro","anchor":"url-front-officielle-primary-front-url"},{"id":"v1.0-dev-28-routing-urls-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"28-routing-urls","chapterTitle":"URLs et routing","heading":"Consulter l'URL par environnement","snippet":"L'endpoint `GET /app-routes/primary-front-url-by-environment?appId=` résout la route désignée et calcule son FQDN pour chaque environnement de l'app :\n\n| Statut | Signification |\n|--------|-----------","anchor":"consulter-lurl-par-environnement"},{"id":"v1.0-dev-29-vars-secrets-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"29-vars-secrets","chapterTitle":"Variables et secrets","heading":"1. Architecture : déclarer ce que le service attend","snippet":"Quand tu crées une ServiceDefinition, tu listes les variables que ton service consomme :\n\n```\nServiceDefinition \"backend\"\n├── requires JWT_SECRET\n├── requires DATABASE_URL\n├── requires S3_BUCKET\n└── r","anchor":"1-architecture-dclarer-ce-que-le-service-attend"},{"id":"v1.0-dev-29-vars-secrets-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"29-vars-secrets","chapterTitle":"Variables et secrets","heading":"2. Configuration d'un environnement","snippet":"La **Configuration** d'un environnement est l'**inventaire des valeurs disponibles** dans cet env, à partir desquelles tes services peuvent se servir. Elle est **commune à tous les services de l'envir","anchor":"2-configuration-dun-environnement"},{"id":"v1.0-dev-29-vars-secrets-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"29-vars-secrets","chapterTitle":"Variables et secrets","heading":"D'où viennent les entrées de Configuration","snippet":"| Source | Exemple | Géré par |\n|--------|---------|----------|\n| **Plateforme** | URL interne d'un service Wakastart (Discovery, IAM…) | Wakastart (auto-généré, dynamique) |\n| **Environnement** | URL","anchor":"do-viennent-les-entres-de-configuration"},{"id":"v1.0-dev-29-vars-secrets-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"29-vars-secrets","chapterTitle":"Variables et secrets","heading":"Secret vs non-secret","snippet":"Chaque entrée de configuration peut être marquée **secret** ou non :\n\n| | Lecture après création | Visible dans l'UI | Usage typique |\n|--|----------------------|-------------------|---------------|\n|","anchor":"secret-vs-non-secret"},{"id":"v1.0-dev-29-vars-secrets-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"29-vars-secrets","chapterTitle":"Variables et secrets","heading":"3. Binding : connecter un service à la Configuration","snippet":"Pour chaque ServiceInstance, tu fais un **binding** entre une variable attendue par le service (déclarée dans sa ServiceDefinition) et une entrée de la Configuration de l'env.\n\n```\nServiceInstance \"ba","anchor":"3-binding-connecter-un-service-la-configuration"},{"id":"v1.0-dev-29-vars-secrets-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"29-vars-secrets","chapterTitle":"Variables et secrets","heading":"Mutualiser : une valeur, plusieurs services","snippet":"Si plusieurs services ont besoin de la **même** valeur (ex: `STRIPE_API_KEY` utilisée par `backend` et `worker`), **ne crée pas deux entrées identiques**. Crée **une seule entrée** dans la Configurati","anchor":"mutualiser-une-valeur-plusieurs-services"},{"id":"v1.0-dev-29-vars-secrets-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"29-vars-secrets","chapterTitle":"Variables et secrets","heading":"Les variables plateforme sont dynamiques","snippet":"Les entrées générées par la plateforme ou par l'environnement (URL de la BDD, URL d'un service interne, hostname public d'un autre service de l'app, credentials S3…) sont **dynamiques** : si la ressou","anchor":"les-variables-plateforme-sont-dynamiques"},{"id":"v1.0-dev-37-url-redirects-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"37-url-redirects","chapterTitle":"Redirections d'URL","heading":"Bloc Source — immuable après création","snippet":"| Champ | Description |\n|-------|--------------|\n| **Domaine** | Un domaine `CUSTOM` appartenant à l'app, ou un domaine `PLATFORM_MANAGED` commun à toute la plateforme (ex. `y.wakastart.app` sur dev) ","anchor":"bloc-source-immuable-aprs-cration"},{"id":"v1.0-dev-37-url-redirects-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"37-url-redirects","chapterTitle":"Redirections d'URL","heading":"Bloc Destination — éditable à tout moment","snippet":"| Champ | Description |\n|-------|--------------|\n| **Route (AppRoute)** | Route existante de l'app à cibler |\n| **Environnement** | Environnement dans lequel la route est provisionnée |\n| **Path** | C","anchor":"bloc-destination-ditable-tout-moment"},{"id":"v1.0-dev-37-url-redirects-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"37-url-redirects","chapterTitle":"Redirections d'URL","heading":"Statuts","snippet":"Cycle de vie standard des ressources Wakastart :\n\n| Statut | Signification |\n|--------|----------------|\n| `PENDING` | Redirection créée en DB, en attente de traitement par l'operator |\n| `PROVISIONIN","anchor":"statuts"},{"id":"v1.0-dev-37-url-redirects-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"37-url-redirects","chapterTitle":"Redirections d'URL","heading":"Mécanisme technique","snippet":"Le routing applicatif classique de Wakastart passe par Gateway API + Istio, via une `HttpRoute` avec un filtre `RequestRedirectFilter` pour les redirections simples. Ce mécanisme **ne suffit pas** ici","anchor":"mcanisme-technique"},{"id":"v1.0-dev-37-url-redirects-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"37-url-redirects","chapterTitle":"Redirections d'URL","heading":"Redirections à l'échelle de l'app (App-scope)","snippet":"Les scopes `NETWORK` et `CUSTOMER` ci-dessus s'adressent aux tenants en aval de l'app. Le scope **`APP`** répond à un autre besoin : permettre à **l'équipe de l'app elle-même** de rediriger une URL ve","anchor":"redirections-lchelle-de-lapp-app-scope"},{"id":"v1.0-dev-37-url-redirects-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"37-url-redirects","chapterTitle":"Redirections d'URL","heading":"AppUrlRedirect (Architecture) → AppUrlRedirectInstance (par environnement)","snippet":"Comme le reste de l'architecture, une redirection App-scope se déclare **une fois**, sans jamais choisir d'environnement, puis s'instancie **par environnement** :\n\n| Niveau | Ressource | Ce que tu déc","anchor":"appurlredirect-architecture-appurlredirectinstance-par-environnement"},{"id":"v1.0-dev-37-url-redirects-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"37-url-redirects","chapterTitle":"Redirections d'URL","heading":"Même mécanisme technique","snippet":"Une redirection App-scope réutilise exactement le composant **HAProxy mutualisé** (`wakastart-redirects`) décrit ci-dessus : mêmes ressources standard côté API infra (`DnsRecord`, `ListenerSet`, `Http","anchor":"mme-mcanisme-technique"},{"id":"v1.0-dev-37-url-redirects-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"37-url-redirects","chapterTitle":"Redirections d'URL","heading":"Limites connues","snippet":"- **RBAC** : pas de contrôle d'accès fin au-delà de `WakaAdmin` / `OwnerAdmin` (accès complet aux redirections), en plus du cloisonnement Network/Customer standard.\n- **Plafond** : 20 redirections max","anchor":"limites-connues"},{"id":"v1.0-dev-30-environments-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"30-environments","chapterTitle":"Environnements","heading":"Champs principaux d'un environnement","snippet":"| Champ | Exemple | Rôle |\n|-------|---------|------|\n| `env` | `dev` / `prod` / `staging` | Type d'environnement |\n| `shortname` | `exemple` | Surnom court de l'app dans cet env |\n| `slug` | `exemple","anchor":"champs-principaux-dun-environnement"},{"id":"v1.0-dev-30-environments-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"30-environments","chapterTitle":"Environnements","heading":"Cycle de vie d'un env","snippet":"```\nACTIVE → (pause) → PAUSED → (resume) → ACTIVE\n ↓\nDELETING → (cleanup) → supprimé\n```","anchor":"cycle-de-vie-dun-env"},{"id":"v1.0-dev-30-environments-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"30-environments","chapterTitle":"Environnements","heading":"Le tableau de bord d'un environnement","snippet":"Quand tu cliques sur un environnement, tu accèdes à :\n\n| Onglet | Contenu |\n|--------|---------|\n| **Résumé** | Vue d'ensemble (services up, dernière deploy, health) |\n| **Services** | Liste des Servi","anchor":"le-tableau-de-bord-dun-environnement"},{"id":"v1.0-dev-32-builds-vs-deployments-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"32-builds-vs-deployments","chapterTitle":"Builds vs Deployments","heading":"Workflow typique","snippet":"1. Tu commits du code et tu push sur `main`\n2. Wakastart **build** : `main` HEAD → image `:abc123`\n3. Une fois `SUCCEEDED`, en mode AUTO, l'image est **deployed** dans les environnements qui surveille","anchor":"workflow-typique"},{"id":"v1.0-dev-32-builds-vs-deployments-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"32-builds-vs-deployments","chapterTitle":"Builds vs Deployments","heading":"Modes de déploiement (DeploymentMode)","snippet":"| Mode | Comportement |\n|------|--------------|\n| `AUTO` | Auto-deploy dès qu'un build sur la branche surveillée réussit |\n| `MANUAL` | Tu choisis explicitement quand déployer (et quelle image) |","anchor":"modes-de-dploiement-deploymentmode"},{"id":"v1.0-dev-33-workflow-complete-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"33-workflow-complete","chapterTitle":"Workflow complet — créer une app de zéro","heading":"Étape 1 — Créer l'App","snippet":"Tu vas dans l'UI, \"Nouvelle App\", tu donnes un nom. Wakastart crée :\n\n- L'enregistrement `App` en DB\n- Un espace dédié dans le registry pour tes futures images Docker\n- Un espace dédié dans le coffre-","anchor":"tape-1-crer-lapp"},{"id":"v1.0-dev-33-workflow-complete-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"33-workflow-complete","chapterTitle":"Workflow complet — créer une app de zéro","heading":"Étape 2 — Définir l'Architecture","snippet":"Tu navigues dans **Infra → Architecture**. Tu crées :\n\n1. **Un Repository** managé `exemple-backend` (Wakastart crée le repo sur GitHub via l'org `Waka-Start`)\n2. **Une ServiceDefinition** `backend` (","anchor":"tape-2-dfinir-larchitecture"},{"id":"v1.0-dev-33-workflow-complete-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"33-workflow-complete","chapterTitle":"Workflow complet — créer une app de zéro","heading":"Étape 3 — Créer un environnement","snippet":"Tu crées un environnement `dev` :\n\n- gitRef: `main`\n- autoDeploy: true\n\n→ Wakastart crée pour cet environnement :\n\n- Un namespace Kubernetes dédié qui isole les ressources de l'env\n- Les DatabaseInsta","anchor":"tape-3-crer-un-environnement"},{"id":"v1.0-dev-33-workflow-complete-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"33-workflow-complete","chapterTitle":"Workflow complet — créer une app de zéro","heading":"Étape 4 — Build et déployer","snippet":"Tu commits du code, tu push sur `main`. Wakastart :\n\n1. Détecte le push via webhook GitHub\n2. Crée un **Build** PENDING\n3. Le build passe BUILDING → PUSHING → SUCCEEDED\n4. Mode AUTO → l'image est **dé","anchor":"tape-4-build-et-dployer"},{"id":"v1.0-dev-33-workflow-complete-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"33-workflow-complete","chapterTitle":"Workflow complet — créer une app de zéro","heading":"Étape 5 — Promouvoir en prod","snippet":"Tu crées un environnement `prod` :\n\n- gitRef: `prod` (branche dédiée)\n- autoDeploy: true\n- Tu overrides ta DatabaseInstance : `mode: MANAGED` (PostgreSQL managé, HA + backups auto)\n- Tu ajoutes un dom","anchor":"tape-5-promouvoir-en-prod"},{"id":"v1.0-dev-33-workflow-complete-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"33-workflow-complete","chapterTitle":"Workflow complet — créer une app de zéro","heading":"Questions fréquentes","snippet":"**\"Pourquoi y a-t-il une distinction Definition / Instance ?\"**\n→ Pour que tu puisses définir ton architecture **une seule fois** et la dupliquer dans plusieurs environnements avec des overrides locau","anchor":"questions-frquentes"},{"id":"v1.0-dev-34-deployment-practices-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"1. Variables d'environnement","snippet":"Chaque fichier `.env.example` constitue un **contrat de configuration**. Il doit être exhaustif, auto-documenté et maintenu à jour à chaque évolution du projet.","anchor":"1-variables-denvironnement"},{"id":"v1.0-dev-34-deployment-practices-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"1.1 Règles obligatoires pour chaque variable","snippet":"| Icône | Attribut | Exigence |\n|---|---|---|\n| 📝 | Exemple de valeur | Fournir une valeur d'exemple réelle et fonctionnelle. Pas de placeholder vide type `xxx` ou `changeme`. |\n| 📌 | Description co","anchor":"11-rgles-obligatoires-pour-chaque-variable"},{"id":"v1.0-dev-34-deployment-practices-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"1.2 Exemple de documentation","snippet":"```env\n# URL de l'API backend consommée par le frontend.\n# TYPE: URL publique (accessible depuis le navigateur de l'utilisateur).\n# OBLIGATOIRE — sans cette variable, toutes les requêtes API échouent.","anchor":"12-exemple-de-documentation"},{"id":"v1.0-dev-34-deployment-practices-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"1.3 `NEXT_PUBLIC_*` vs variables runtime (Next.js)","snippet":"Les variables `NEXT_PUBLIC_*` sont **compilées au moment du build** par Next.js et inlinées dans le bundle JS. Elles ne peuvent pas être modifiées à l'exécution du conteneur.\n\nSi une URL doit pouvoir ","anchor":"13-next_public_-vs-variables-runtime-nextjs"},{"id":"v1.0-dev-34-deployment-practices-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"2. Dockerfile et migrations Prisma","snippet":"En l'absence d'outillage CI/CD avancé, toute application nécessitant une base de données doit garantir l'application automatique des migrations Prisma au démarrage du conteneur.","anchor":"2-dockerfile-et-migrations-prisma"},{"id":"v1.0-dev-34-deployment-practices-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"2.1 Entrypoint obligatoire pour les applications avec Prisma","snippet":"Le Dockerfile de toute application backend utilisant Prisma doit déléguer le démarrage à un script `entrypoint.sh`. Ce script applique les migrations avant de démarrer le processus Node.js principal.\n","anchor":"21-entrypoint-obligatoire-pour-les-applications-avec-prisma"},{"id":"v1.0-dev-34-deployment-practices-6","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"2.2 Pièges à éviter","snippet":"- ✅ `prisma` doit figurer dans les `dependencies` (et **non** `devDependencies`) pour être disponible lors de l'exécution du conteneur de production.\n- 🚨 Ne **jamais** utiliser `pnpm prune --prod` sa","anchor":"22-piges-viter"},{"id":"v1.0-dev-34-deployment-practices-7","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"2.3 Seed optionnel : injecter des données initiales ou de test","snippet":"Le conteneur de votre service est le seul point d'entrée vers sa base de données en ligne. Pour **réinjecter des données** (jeu de référence, données de démo, ou les données de test de votre environne","anchor":"23-seed-optionnel-injecter-des-donnes-initiales-ou-de-test"},{"id":"v1.0-dev-34-deployment-practices-8","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"3. TypeScript et build NestJS / Node.js","snippet":"Les erreurs de build TypeScript sont une cause fréquente de déploiements silencieusement cassés.\n\n| Règle | Détail |\n|---|---|\n| **`rootDir` obligatoire** dans `tsconfig.build.json` | Toujours déclare","anchor":"3-typescript-et-build-nestjs-nodejs"},{"id":"v1.0-dev-34-deployment-practices-9","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"4. Runtime config du frontend (Next.js)","snippet":"Les applications Next.js déployées en conteneur ont deux sources de configuration : les variables `NEXT_PUBLIC_*` (compilées au build) et les variables injectées à l'exécution via `window.__RUNTIME_CO","anchor":"4-runtime-config-du-frontend-nextjs"},{"id":"v1.0-dev-34-deployment-practices-10","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"Règles pour la runtime config","snippet":"- L'`entrypoint.sh` du frontend doit lire les variables **telles qu'elles sont définies dans le déploiement K8s** (`NEXT_PUBLIC_API_URL`, `KEYCLOAK_PUBLIC_URL`, etc.), et **non** des alias inventés lo","anchor":"rgles-pour-la-runtime-config"},{"id":"v1.0-dev-34-deployment-practices-11","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"5. Intégration S3 et Object Storage","snippet":"Les adaptateurs S3 doivent gérer correctement les URLs d'endpoint pour éviter des erreurs de connectivité silencieuses.","anchor":"5-intgration-s3-et-object-storage"},{"id":"v1.0-dev-34-deployment-practices-12","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"Règles pour les endpoints S3","snippet":"- Ne **jamais** préfixer mécaniquement `https://` sur une variable d'endpoint : si la variable contient déjà le protocole, la double-préfixation produit une URL invalide (`https://https://…`) non déte","anchor":"rgles-pour-les-endpoints-s3"},{"id":"v1.0-dev-34-deployment-practices-13","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"6. Authentification et flux OAuth / Keycloak","snippet":"> Voir aussi [Authentification — Concepts & Flow](/v1.0/dev/03-authentication-overview) pour le flux OAuth général. Les règles ci-dessous sont des **pièges concrets** rencontrés sur des services en pr","anchor":"6-authentification-et-flux-oauth-keycloak"},{"id":"v1.0-dev-34-deployment-practices-14","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"6.1 `redirect_uri`","snippet":"Le `redirect_uri` envoyé dans la requête d'autorisation doit être **strictement identique** à celui utilisé lors de l'échange de code côté serveur. Toute divergence provoque un rejet Keycloak.\n\nLe ser","anchor":"61-redirect_uri"},{"id":"v1.0-dev-34-deployment-practices-15","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"6.2 Clés `sessionStorage`","snippet":"Toutes les clés `sessionStorage` utilisées dans le flux OAuth (`realm`, `client_id`, `state`, `code_verifier`…) doivent être déclarées dans un **fichier de constantes partagé** entre tous les modules ","anchor":"62-cls-sessionstorage"},{"id":"v1.0-dev-34-deployment-practices-16","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"6.3 `login_hint`","snippet":"Lorsque l'email de l'utilisateur est connu avant la redirection vers Keycloak, transmettre le paramètre standard OIDC `login_hint` pour pré-remplir le formulaire Keycloak et éviter une double saisie.","anchor":"63-login_hint"},{"id":"v1.0-dev-34-deployment-practices-17","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"6.4 Multi-organisations (Discovery)","snippet":"Si l'API Discovery peut retourner plusieurs comptes pour un même email (plusieurs realms Keycloak), le frontend doit afficher un écran de **sélection d'organisation** avant de rediriger. Ne jamais pre","anchor":"64-multi-organisations-discovery"},{"id":"v1.0-dev-34-deployment-practices-18","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"6.5 URL de Keycloak côté serveur","snippet":"La variable `KEYCLOAK_URL` (URL interne ou publique pour les appels server-side) doit être **explicitement définie** dans la configuration K8s. Sans elle, les appels tombent sur `localhost:8080` et éc","anchor":"65-url-de-keycloak-ct-serveur"},{"id":"v1.0-dev-34-deployment-practices-19","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"7. Migrations Prisma (au-delà du runtime)","snippet":"Les migrations de base de données doivent être gérées de manière déterministe et reproductible entre les environnements.","anchor":"7-migrations-prisma-au-del-du-runtime"},{"id":"v1.0-dev-34-deployment-practices-20","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"34-deployment-practices","chapterTitle":"Bonnes pratiques de déploiement","heading":"Règles pour les migrations Prisma","snippet":"- Le répertoire `prisma/migrations/` doit contenir une **migration initiale** générée par `prisma migrate dev` qui crée l'intégralité du schéma. Les scripts SQL en vrac non gérés par Prisma ne sont pa","anchor":"rgles-pour-les-migrations-prisma"},{"id":"v1.0-dev-35-glossary-deploy-0","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"35-glossary-deploy","chapterTitle":"Glossaire de l'hébergement","heading":"Concepts généraux","snippet":"- **PaaS** (Platform as a Service) : tu codes ton app, la plateforme l'héberge — elle fournit l'infra, l'OS, le runtime et le pipeline de déploiement. Opposé : IaaS (tu gères les VMs).\n- **Kubernetes ","anchor":"concepts-gnraux"},{"id":"v1.0-dev-35-glossary-deploy-1","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"35-glossary-deploy","chapterTitle":"Glossaire de l'hébergement","heading":"Images et registry","snippet":"- **Docker image** : un paquet figé qui contient ton code + ses dépendances + l'OS minimal pour tourner. Reproductible.\n- **Registry** : un stockage d'images Docker. Wakastart fournit un registry priv","anchor":"images-et-registry"},{"id":"v1.0-dev-35-glossary-deploy-2","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"35-glossary-deploy","chapterTitle":"Glossaire de l'hébergement","heading":"Stockage","snippet":"- **Bucket S3** : conteneur de fichiers (objets) accessible via HTTP, identifié par un nom unique. Pas de hiérarchie de dossiers réelle, juste des clés.\n- **BDD relationnelle** (PostgreSQL, MySQL) : t","anchor":"stockage"},{"id":"v1.0-dev-35-glossary-deploy-3","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"35-glossary-deploy","chapterTitle":"Glossaire de l'hébergement","heading":"Sécurité","snippet":"- **Secret manager** : coffre-fort chiffré qui stocke les credentials sensibles (mots de passe BDD, clés API, certificats). Wakastart en fournit un, isolé par app. Tu n'y accèdes jamais directement : ","anchor":"scurit"},{"id":"v1.0-dev-35-glossary-deploy-4","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"35-glossary-deploy","chapterTitle":"Glossaire de l'hébergement","heading":"Réseau","snippet":"- **Gateway** : entrée de la plateforme pour le trafic HTTP entrant. C'est elle qui termine le TLS (certificats) et applique les règles de routage HttpRoute.\n- **HttpRoute** : règle de routage qui dit","anchor":"rseau"},{"id":"v1.0-dev-35-glossary-deploy-5","version":"v1.0","sectionId":"dev","sectionLabel":"Développeur","chapterId":"35-glossary-deploy","chapterTitle":"Glossaire de l'hébergement","heading":"CI/CD","snippet":"- **CI** (Continuous Integration) : tests automatiques sur chaque commit. Pas géré par Wakastart (tu utilises GitHub Actions, Jenkins, etc.).\n- **CD** (Continuous Deployment) : déploiement automatique","anchor":"cicd"}],"groupsBySectionId":{"user":[{"id":"premiers-pas","label":"Premiers pas","icon":"Rocket","chapters":[{"id":"01-getting-started","version":"v1.0","section":"user","title":"Connexion et authentification","description":"Comment se connecter à WakaStart : saisie de l'e-mail, sélection de l'organisation, mot de passe et premier accès.","order":1,"group":"premiers-pas","icon":"LogIn","content":"$11"}]},{"id":"tableau-de-bord","label":"Tableau de bord","icon":"LayoutDashboard","chapters":[{"id":"02-dashboard","version":"v1.0","section":"user","title":"Tableau de bord principal","description":"Présentation du tableau de bord WakaStart : KPIs, fil d'activité, en-tête et filtre global AdminCrumb.","order":2,"group":"tableau-de-bord","icon":"LayoutDashboard","content":"$12"}]},{"id":"organisation","label":"Organisation","icon":"Building2","chapters":[{"id":"03-partners","version":"v1.0","section":"user","title":"Partenaires","description":"Créer, modifier et administrer les partenaires de la plateforme WakaStart.","order":3,"group":"organisation","icon":"Handshake","content":"$13"},{"id":"04-networks","version":"v1.0","section":"user","title":"Réseaux","description":"Gérer les réseaux de votre plateforme WakaStart : création, configuration et fiche détail.","order":4,"group":"organisation","icon":"Network","content":"$14"},{"id":"05-customers","version":"v1.0","section":"user","title":"Clients","description":"Créer, configurer et administrer les organisations clientes de votre réseau.","order":5,"group":"organisation","icon":"Building","content":"$15"},{"id":"06-users","version":"v1.0","section":"user","title":"Utilisateurs","description":"Gérer les utilisateurs administrateurs et les comptes d'un Client : création, permissions, rôles HDS et profils.","order":6,"group":"organisation","icon":"Users","content":"$16"},{"id":"07-teams","version":"v1.0","section":"user","title":"Équipes","description":"Regrouper les utilisateurs d'un client en équipes avec des niveaux d'accès différenciés.","order":7,"group":"organisation","icon":"UsersRound","content":"$17"}]},{"id":"applications","label":"Applications","icon":"AppWindow","chapters":[{"id":"08-applications","version":"v1.0","section":"user","title":"Applications","description":"Créer, configurer et déployer des applications dans la plateforme WakaStart.","order":8,"group":"applications","icon":"AppWindow","content":"$18"},{"id":"09-profiles-rights","version":"v1.0","section":"user","title":"Profils et droits","description":"Gérer les profils applicatifs et les droits pour contrôler les accès aux fonctionnalités.","order":9,"group":"applications","icon":"ShieldCheck","content":"$19"},{"id":"10-api-keys","version":"v1.0","section":"user","title":"Clés API","description":"Créer et gérer les clés API pour l'accès programmatique aux services WakaStart.","order":10,"group":"applications","icon":"KeyRound","content":"$1a"}]},{"id":"support","label":"Support & suivi","icon":"Ticket","chapters":[{"id":"27-tickets","version":"v1.0","section":"user","title":"Gestion des tickets","description":"Suivi des tickets de support et de développement liés à vos applications : création, statuts, commentaires, pièces jointes et historique.","order":27,"group":"support","icon":"Ticket","content":"$1b"}]},{"id":"securite-conformite","label":"Sécurité & conformité","icon":"ShieldCheck","chapters":[{"id":"11-audit-logs","version":"v1.0","section":"user","title":"Journaux d'audit","description":"Consulter, filtrer et exporter les journaux d'audit de la plateforme WakaStart.","order":11,"group":"securite-conformite","icon":"ScrollText","content":"$1c"},{"id":"15-antivirus","version":"v1.0","section":"user","title":"Module Antivirus","description":"Surveiller et administrer le service antivirus : quarantaine, file d'attente et politiques.","order":15,"group":"securite-conformite","icon":"ShieldAlert","content":"$1d"},{"id":"20-hds","version":"v1.0","section":"user","title":"Module HDS","description":"Hébergement de Données de Santé : vue d'ensemble, transactions, audit d'intégrité, sécurité et conformité.","order":20,"group":"securite-conformite","icon":"HeartPulse","content":"$1e"},{"id":"16-stellar","version":"v1.0","section":"user","title":"Module Stellar (preuves blockchain)","description":"Consulter les preuves d'intégrité ancrées sur la blockchain Stellar.","order":16,"group":"securite-conformite","icon":"Star","content":"$1f"}]},{"id":"business","label":"Business","icon":"TrendingUp","chapters":[{"id":"12-credits","version":"v1.0","section":"user","title":"Crédits","description":"Suivre la consommation et le solde de crédits de votre organisation.","order":12,"group":"business","icon":"Coins","content":"$20"},{"id":"13-billing","version":"v1.0","section":"user","title":"Facturation","description":"Acheter des crédits et gérer la facturation de votre compte WakaStart.","order":13,"group":"business","icon":"CreditCard","content":"$21"},{"id":"17-projects","version":"v1.0","section":"user","title":"Projets","description":"Créer et gérer des projets WakaStart : liste, éditeur, équipe, frise chronologique et GED.","order":17,"group":"business","icon":"FolderKanban","content":"$22"},{"id":"21-prospects","version":"v1.0","section":"user","title":"Prospects et gestion commerciale","description":"Suivre les opportunités commerciales, créer des devis et estimer les coûts d'un projet WakaStart.","order":21,"group":"business","icon":"TrendingUp","content":"$23"},{"id":"22-entities","version":"v1.0","section":"user","title":"Entités juridiques et contacts","description":"Gérer le référentiel des organisations clientes et de leurs interlocuteurs.","order":22,"group":"business","icon":"Landmark","content":"$24"},{"id":"25-pricing","version":"v1.0","section":"user","title":"Module Tarification (Pricing)","description":"Définir le coût en crédits de chaque action de la plateforme avec des tarifs dérogatoires par réseau ou client.","order":25,"group":"business","icon":"Tag","content":"$25"}]},{"id":"personnalisation","label":"Personnalisation","icon":"Palette","chapters":[{"id":"14-media","version":"v1.0","section":"user","title":"Médias","description":"Gérer les fichiers médias de la plateforme, configurer le service et suivre les traitements.","order":14,"group":"personnalisation","icon":"Image","content":"$26"},{"id":"18-settings","version":"v1.0","section":"user","title":"Paramètres","description":"Configurer l'apparence, les cloud providers, et les features réseau et client.","order":18,"group":"personnalisation","icon":"Settings","content":"$27"},{"id":"23-identity-providers","version":"v1.0","section":"user","title":"Fournisseurs d'identité (SSO)","description":"Configurer des connexions SSO depuis des annuaires externes : Google, Microsoft, Okta, SAML 2.0.","order":23,"group":"personnalisation","icon":"KeySquare","content":"$28"}]},{"id":"administration-plateforme","label":"Administration plateforme","icon":"Server","chapters":[{"id":"24-backup","version":"v1.0","section":"user","title":"Sauvegarde et restauration","description":"Exporter et importer des configurations d'applications, réseaux et clients via des blueprints.","order":24,"group":"administration-plateforme","icon":"DatabaseBackup","content":"$29"},{"id":"26-wakaadmin","version":"v1.0","section":"user","title":"Administration plateforme (WakaAdmin)","description":"Administration avancée de la plateforme : domaines, gateways, registre de conteneurs, coffre de secrets, dépôts, SMTP et monitoring.","order":26,"group":"administration-plateforme","icon":"Server","content":"$2a"}]},{"id":"compte-personnel","label":"Compte personnel","icon":"UserCircle","chapters":[{"id":"19-profile","version":"v1.0","section":"user","title":"Mon profil","description":"Modifier vos informations personnelles, préférences et consulter vos droits dans WakaStart.","order":19,"group":"compte-personnel","icon":"UserCircle","content":"$2b"}]},{"id":"annexe","label":"Annexe","icon":"BookMarked","chapters":[{"id":"99-glossary","version":"v1.0","section":"user","title":"Glossaire","description":"Définitions des termes et concepts clés de la plateforme WakaStart.","order":99,"group":"annexe","icon":"BookMarked","content":"$2c"}]}],"dev":[{"id":"premiers-pas","label":"Premiers pas","icon":"Rocket","chapters":[{"id":"01-architecture","version":"v1.0","section":"dev","title":"Architecture","description":"Vue d'ensemble de l'architecture Wakapp : hiérarchie multi-tenant, services, flux de communication et modes d'accès.","order":1,"group":"premiers-pas","icon":"GitGraph","content":"$2d"},{"id":"02-discovery","version":"v1.0","section":"dev","title":"Discovery — Identifier l'utilisateur","description":"Utiliser le service Discovery pour résoudre l'organisation d'un utilisateur avant l'authentification.","order":2,"group":"premiers-pas","icon":"Search","content":"$2e"}]},{"id":"authentification","label":"Authentification","icon":"Lock","chapters":[{"id":"03-authentication-overview","version":"v1.0","section":"dev","title":"Authentification — Concepts & Flow","description":"Vue d'ensemble du flow OAuth2 PKCE Wakastart : concepts clés, diagramme complet et prérequis Keycloak.","order":3,"group":"authentification","icon":"Lock","content":"$2f"},{"id":"04-authentication-implementation","version":"v1.0","section":"dev","title":"Authentification — Implémentation PKCE","description":"Code complet du flow PKCE : génération, start-login, échange, enrichissement, cookies et logout.","order":4,"group":"authentification","icon":"KeyRound","content":"$30"},{"id":"05-me-endpoint-payload","version":"v1.0","section":"dev","title":"Contexte utilisateur — Structure du payload /me","description":"Structure complète du payload /me : identité, niveaux d'accès, équipes, droits applicatifs et features.","order":5,"group":"authentification","icon":"UserCheck","content":"$31"},{"id":"06-me-endpoint-caching","version":"v1.0","section":"dev","title":"Contexte utilisateur — Cache & Invalidation","description":"Quand appeler /me, stratégie de cache React, invalidation après refresh token et bonnes pratiques.","order":6,"group":"authentification","icon":"RefreshCw","content":"$32"}]},{"id":"securite","label":"Sécurité","icon":"ShieldCheck","chapters":[{"id":"07-access-control-model","version":"v1.0","section":"dev","title":"Contrôle d'accès — Modèle & Cascade","description":"Les 2 vecteurs de droits Wakastart : adminLevel et appRights (droits resource.action), et la vérification de features activées.","order":7,"group":"securite","icon":"ShieldCheck","content":"$33"},{"id":"08-access-control-implementation","version":"v1.0","section":"dev","title":"Contrôle d'accès — Guards & Hooks","description":"Implémentation complète : hook useAppRights, composant Protected, guard NestJS AppRightGuard.","order":8,"group":"securite","icon":"Shield","content":"$34"},{"id":"09-access-control-features","version":"v1.0","section":"dev","title":"Contrôle d'accès — Feature Flags","description":"Cascade de features App/Network/Customer, activation conditionnelle et intégration dans les guards.","order":9,"group":"securite","icon":"ToggleLeft","content":"$35"},{"id":"12-best-practices-security","version":"v1.0","section":"dev","title":"Bonnes pratiques — Sécurité","description":"Tokens, secrets, HTTPS, CSP, logs : les règles de sécurité non négociables pour une Wakapp en production.","order":12,"group":"securite","icon":"CheckCircle","content":"$36"},{"id":"13-best-practices-perf-observability","version":"v1.0","section":"dev","title":"Bonnes pratiques — Performance & Observabilité","description":"Cache, refresh proactif, pagination, TanStack Query, métriques Prometheus et structured logging.","order":13,"group":"securite","icon":"Activity","content":"$37"},{"id":"17-pitfalls","version":"v1.0","section":"dev","title":"Pièges classiques d'intégration","description":"Les 10 erreurs les plus fréquentes lors de l'intégration d'une Wakapp : symptôme, cause et solution.","order":17,"group":"securite","icon":"Bug","content":"$38"}]},{"id":"utilisation","label":"Utilisation de l'API","icon":"Plug","chapters":[{"id":"10-api-conventions","version":"v1.0","section":"dev","title":"Utilisation de l'API — Conventions REST","description":"Authentifier les requêtes, pagination, filtres, multi-tenant automatique et format d'erreur unifié.","order":10,"group":"utilisation","icon":"Plug","content":"$39"},{"id":"11-api-headers-rate-limits","version":"v1.0","section":"dev","title":"Utilisation de l'API — Headers & Rate Limits","description":"Headers requis et optionnels, idempotence, CORS, rate limiting et backoff exponentiel.","order":11,"group":"utilisation","icon":"Gauge","content":"$3a"},{"id":"14-endpoint-reference","version":"v1.0","section":"dev","title":"Référence des endpoints","description":"Tableau exhaustif de tous les endpoints Discovery, Auth, profil, CRUD, invitations et modules disponibles pour une WakaApp.","order":14,"group":"utilisation","icon":"BookOpen","content":"$3b"},{"id":"15-errors-http","version":"v1.0","section":"dev","title":"Erreurs — Codes HTTP","description":"Format d'erreur unifié, codes HTTP 400 à 5xx, causes et stratégies de gestion pour une Wakapp robuste.","order":15,"group":"utilisation","icon":"AlertTriangle","content":"$3c"},{"id":"16-errors-business","version":"v1.0","section":"dev","title":"Erreurs — Codes métier","description":"Codes d'erreur métier Wakastart, messages exacts testables programmatiquement et mappings d'état.","order":16,"group":"utilisation","icon":"AlertCircle","content":"$3d"}]},{"id":"modules","label":"Modules","icon":"Blocks","chapters":[{"id":"18-invitations-create","version":"v1.0","section":"dev","title":"API Invitations — Création","description":"Créer une invitation : prérequis, endpoint POST /api/invitations, body, réponse et gestion d'erreurs.","order":18,"group":"modules","icon":"Mail","content":"$3e"},{"id":"19-invitations-verify-accept","version":"v1.0","section":"dev","title":"API Invitations — Vérification & Acceptation","description":"Endpoints verify et accept : implémentation de la page d'acceptation, effets serveur et pièges.","order":19,"group":"modules","icon":"UserPlus","content":"$3f"},{"id":"20-mcp-server-overview","version":"v1.0","section":"dev","title":"MCP Server — Vue d'ensemble","description":"Le serveur MCP WakaStart hébergé sur docs.wakastart.app : 5 tools, resources disponibles et caractéristiques techniques.","order":20,"group":"modules","icon":"Bot","content":"$40"},{"id":"21-mcp-server-claude-code-setup","version":"v1.0","section":"dev","title":"MCP Server — Configuration Claude Code","description":"Configurer Claude Code avec .mcp.json pour accéder au serveur MCP WakaStart sur docs.wakastart.app.","order":21,"group":"modules","icon":"Settings","content":"$41"}]},{"id":"modele-architecture","label":"Modèle d'architecture","icon":"LayoutDashboard","chapters":[{"id":"22-platform-overview","version":"v1.0","section":"dev","title":"Vue d'ensemble de la plateforme","description":"Wakastart est une plateforme PaaS qui héberge ton app — tu déclares ses composants, Wakastart les build et les exécute.","order":22,"group":"modele-architecture","icon":"LayoutDashboard","content":"$42"},{"id":"23-app-hierarchy","version":"v1.0","section":"dev","title":"Hiérarchie App → Environnement → Instances","description":"Le modèle hiérarchique de Wakastart : Architecture (le blueprint) vs Environnements (les instances réelles).","order":23,"group":"modele-architecture","icon":"GitMerge","content":"$43"}]},{"id":"architecture-json","label":"Architecture en JSON","icon":"FileJson","chapters":[{"id":"36-architecture-json","version":"v1.0","section":"dev","title":"Décrire son architecture en JSON","description":"Décrivez l'infrastructure de votre wakapp dans un fichier JSON et importez-la en quelques clics — démarrez vite, clonez une app, ou laissez une IA générer le squelette.","order":36,"group":"architecture-json","icon":"FileJson","content":"$44"}]},{"id":"sources-services","label":"Sources & services","icon":"Package","chapters":[{"id":"24-repositories","version":"v1.0","section":"dev","title":"Repository (dépôt Git)","description":"Repos managés ou importés : la source du code que tu vas builder.","order":24,"group":"sources-services","icon":"Github","content":"\n# Repository (dépôt Git)\n\n> 📍 **Où trouver ça dans l'UI** — Infra → onglet **Architecture** → **Repositories**\n\n> **C'est quoi ?** Un repository est un dépôt de code source sur GitHub. C'est de là que part le code que tu vas builder et déployer.\n\nWakastart distingue **2 types de repos** :\n\n| Type | Description |\n|------|-------------|\n| **Managé** | Wakastart le crée pour toi sur GitHub (sous l'org `Waka-Start`). Pratique pour démarrer rapidement. |\n| **Importé** | Tu donnes l'URL d'un repo qui existe déjà ailleurs (ex: `https://github.com/groupe-jds/biped.git`). Wakastart le consulte mais ne le possède pas. |\n\n## À quoi ça sert un repo dans Wakastart ?\n\nUn repo n'est **pas** un service à lui tout seul. Il fournit le code source qui sera ensuite :\n\n1. Lu pour faire un **Build** (transformer le code en image Docker)\n2. Utilisé pour ses branches/tags (référence Git d'un environnement)\n\nPlusieurs services peuvent venir du même repo (monorepo).\n"},{"id":"25-services","version":"v1.0","section":"dev","title":"Service — composant exécutable","description":"ServiceDefinition (architecture) vs ServiceInstance (environnement) : le pattern 2 niveaux.","order":25,"group":"sources-services","icon":"Box","content":"$45"},{"id":"26-builds","version":"v1.0","section":"dev","title":"Build — du code à l'image Docker","description":"Le pipeline qui transforme ton code Git en image Docker prête à déployer.","order":26,"group":"sources-services","icon":"Package","content":"$46"}]},{"id":"donnees-routing","label":"Bases, stockage, routing","icon":"Database","chapters":[{"id":"27-databases-storage","version":"v1.0","section":"dev","title":"Bases de données et stockage","description":"PostgreSQL, MongoDB, Valkey et buckets S3 : les dépendances persistantes de ton app.","order":27,"group":"donnees-routing","icon":"Database","content":"$47"},{"id":"28-routing-urls","version":"v1.0","section":"dev","title":"URLs et routing","description":"Domaines, sous-domaines et HttpRoutes : comment Wakastart route le trafic HTTP vers tes services.","order":28,"group":"donnees-routing","icon":"Globe","content":"$48"},{"id":"29-vars-secrets","version":"v1.0","section":"dev","title":"Variables et secrets","description":"Comment Wakastart fournit la config à tes services : architecture, configuration d'environnement, binding.","order":29,"group":"donnees-routing","icon":"KeyRound","content":"$49"},{"id":"37-url-redirects","version":"v1.0","section":"dev","title":"Redirections d'URL","description":"Rediriger un sous-domaine Network ou Customer vers une route applicative existante, via un composant HAProxy mutualisé.","order":37,"group":"donnees-routing","icon":"ArrowRightLeft","content":"$4a"}]},{"id":"environnements-lifecycle","label":"Environnements & cycle de vie","icon":"Layers","chapters":[{"id":"30-environments","version":"v1.0","section":"dev","title":"Environnements","description":"Un environnement = une instance complète et isolée de ton app. Champs principaux, cycle de vie, dashboard.","order":30,"group":"environnements-lifecycle","icon":"Layers","content":"$4b"},{"id":"31-resource-lifecycle","version":"v1.0","section":"dev","title":"Cycle de vie d'une ressource","description":"Statuses PENDING → PROVISIONING → PROVISIONED → DESTROYING → DESTROYED.","order":31,"group":"environnements-lifecycle","icon":"Activity","content":"\n# Cycle de vie d'une ressource (status)\n\nToute ressource managée par Wakastart suit un cycle de vie :\n\n```\nPENDING → PROVISIONING → PROVISIONED (ou READY pour les DBs)\n ↓\n (modifications)\n ↓\n DESTROYING → DESTROYED\n```\n\n| Statut | Signification |\n|--------|---------------|\n| `PENDING` | Wakastart a noté ta demande, le travail va commencer |\n| `PROVISIONING` | En cours de création (creating GitHub repo, applying terraform, etc.) |\n| `PROVISIONED` / `READY` | Disponible et utilisable |\n| `FAILED` | Quelque chose s'est mal passé — voir `provisioningError` |\n| `DESTROYING` | Tu as supprimé, cleanup en cours |\n| `DESTROYED` | Cleanup terminé |\n\n→ Tu peux donc voir une ressource passer rapidement de PENDING à PROVISIONING à PROVISIONED, ou rester en PROVISIONING quelques minutes le temps que la plateforme provisionne (ex: création d'une base managée chez le cloud provider).\n"},{"id":"32-builds-vs-deployments","version":"v1.0","section":"dev","title":"Builds vs Deployments","description":"Différence cruciale : un Build produit une image, un Deployment lance des pods. Mode AUTO vs MANUAL.","order":32,"group":"environnements-lifecycle","icon":"GitCompare","content":"$4c"}]},{"id":"workflow","label":"Workflow","icon":"Map","chapters":[{"id":"33-workflow-complete","version":"v1.0","section":"dev","title":"Workflow complet — créer une app de zéro","description":"Narration end-to-end : créer l'App, définir l'architecture, lancer un build, déployer en dev puis en prod.","order":33,"group":"workflow","icon":"Map","content":"$4d"}]},{"id":"bonnes-pratiques","label":"Bonnes pratiques","icon":"CheckCircle","chapters":[{"id":"34-deployment-practices","version":"v1.0","section":"dev","title":"Bonnes pratiques de déploiement","description":"Règles concrètes pour qu'un service applicatif tourne correctement sur Wakastart : .env.example, Dockerfile, migrations Prisma, seed des données, runtime config, S3, OAuth.","order":34,"group":"bonnes-pratiques","icon":"CheckCircle","content":"$4e"}]},{"id":"glossaire","label":"Glossaire","icon":"BookOpen","chapters":[{"id":"35-glossary-deploy","version":"v1.0","section":"dev","title":"Glossaire de l'hébergement","description":"Vocabulaire technique de l'hébergement : PaaS, K8s, Pod, Docker image, Bucket S3, Gateway, etc.","order":35,"group":"glossaire","icon":"BookOpen","content":"$4f"}]},{"id":"references","label":"Références","icon":"BookMarked","chapters":[{"id":"api-reference","version":"v1.0","section":"dev","title":"Référence API","description":"Spec OpenAPI interactive de la Public API WakaStart — parcourez les endpoints, essayez les requêtes.","order":13,"group":"references","icon":"FileCode2","content":"\n# Référence API\n\nCette page charge la spécification OpenAPI complète de la Public API WakaStart dans un lecteur interactif (Scalar).\n"},{"id":"ui-storybook","version":"v1.0","section":"dev","title":"UI Storybook","description":"Documentation visuelle des composants @wakastellar/ui — exemples interactifs, props et variantes.","order":14,"group":"references","icon":"Palette","content":"\n# UI Storybook\n\nCette page intègre le Storybook des composants `@wakastellar/ui` utilisés dans les Wakapps WakaStart.\n"}]}]},"children":"$L50"}]