Apparence
18. API & Intégrations
👔 En clair
La liste des opérations que l'application sait faire côté serveur (créer/activer une campagne, saisir un résultat, déclarer une anomalie…) et les services externes utilisés (Convex, Better Auth, Vercel). Contenu technique — côté métier, retenez surtout le tableau des intégrations tierces (§18.3).
v2 — Convex. Il n'y a plus de couche REST
app/api/*pour le métier : le backend est un ensemble de fonctions Convex groupées par domaine (packages/backend/convex/<domaine>.ts), appelées directement depuis le front (api.<domaine>.<fn>). Les queries sont réactives (le client s'abonne, les vues se rafraîchissent seules) ; les mutations sont transactionnelles. Tout part des wrappers authentifiészQuery/zMutation(functions.ts) → auth + validation Zod + ABAC.
18.1 Domaines de fonctions Convex
Correspondance avec les endpoints v1 (app/api/*). Chaque domaine expose des queries (lecture réactive) et des mutations (écriture), l'autorisation étant appliquée dans la fonction via canInContext.
Domaine (convex/*.ts) | Remplace (v1) | Rôles en écriture | Contenu |
|---|---|---|---|
auth / getCurrentUser | /api/auth/me, /api/auth/logout | authentifié | Identité + rôle + organizationId (Better Auth) |
projects | /api/project | admin (création/édition) | Projets |
modules | /api/modules, /api/modules/setup | admin · setup : admin+consultant | CRUD module + amorçage hiérarchie |
functionalities | /api/functionalities | admin+consultant | Fonctionnalités |
scenarios | /api/scenarios | admin+consultant | Scénarios |
tests | /api/tests | admin+consultant | Flux + création dual/ref-only, proposition, réordonnancement |
etapes | /api/etapes | définitions : admin+consultant · résultat : + testeur | Étapes + résultats + journalisation |
anomalies | /api/anomalies | admin+consultant+testeur | Anomalies + triage |
testRuns | /api/test-runs | admin+consultant+testeur | Runs |
campaigns | /api/campaigns | création/édit : admin+consultant · activation/suppression : admin | Campagnes + activation (snapshot) |
crims | /api/crims | admin+consultant | CRIMs (+ import en masse) |
admin (users) | /api/admin/users | admin | Utilisateurs (rôles, suppression) — via Better Auth |
Erreurs : les fonctions lèvent des erreurs Convex explicites (non authentifié, accès refusé, campagne non active, données invalides). Pas de codes HTTP à gérer côté métier ; la réactivité Convex remplace l'invalidation de cache (revalidatePath) de v1.
18.2 Mutations « logique serveur » (ex-RPC PostgreSQL)
Les fonctions RPC SECURITY DEFINER de v1 deviennent de simples mutations Convex (transactionnelles par nature, pas besoin de SECURITY DEFINER) :
activateCampaign (snapshot), createRefAndSnapshot, createRefOnly, proposeCorrectionTest, addEtapeDual, moveTest / moveScenario / moveFunctionality / moveEtape, deleteEtape, refreshFluxCrims.
Les traversées de hiérarchie et le recalcul des caches s'appuient sur les relationship helpers et triggers convex-helpers.
18.3 Intégrations tierces
| Système | Rôle |
|---|---|
| Convex | Base documentaire réactive + fonctions serveur + File Storage (preuves) |
| Better Auth | Authentification (email/mot de passe) via @convex-dev/better-auth |
| Vercel | Hébergement du front Next.js |
| Jira | ❌ Pas d'intégration API — simple champ texte jiraLink sur l'anomalie (inchangé vs v1) |
18.4 Lecture & écriture : un seul plan (Convex)
En v1, une asymétrie existait : lectures directes depuis le navigateur (client Supabase + RLS), écritures via routes API (requireRole). En v2, les deux passent par Convex : lectures = queries réactives, écritures = mutations, toutes deux authentifiées et autorisées dans la même couche (zQuery/zMutation + ABAC). L'asymétrie disparaît.