BDD-117 — Consultation des données via une connexion API

1. User Story

En tant qu'administrateur,
Je veux parcourir une connexion API Formulaires, choisir un formulaire et visualiser ses réponses dans un tableau,
Afin d'identifier le jeu de données à exploiter (sans exposer la clé API dans le navigateur).

2. Critères d'acceptation

1. L’utilisateur peut sélectionner un formulaire depuis une liste disponible
2. Un bouton permet de charger les réponses du formulaire
3. En cas d’UUID invalide ou de formulaire introuvable un message explicite est affiché
4. En cas de succès, les réponses du formulaire sont chargées et disponibles dans l’application via une vue dédiée aux réponses du formulaire

3. Périmètre fonctionnel

Backend

Fichier	Rôle
back/src/api/connections/browse/connection-browse.controller.ts	GET /connections/:uuid/forms, GET …/forms/:formUuid/responses
back/src/api/connections/browse/connection-browse.service.ts	Liste formulaires (pagination curseur), mapping export JSON → tableau
back/src/api/connections/browse/formulaires.catalog.ts	Chemins M2M (/forms, /export/json/forms/:id/responses)
back/src/api/connections/browse/formulaires.client.ts	Appels HTTP + détection clé révoquée (isApiKeyFailureBody)
back/src/api/connections/browse/dto/connection-browse.dto.ts	DTO Swagger
back/src/api/connections/connections.service.ts	getConnectionContext, markConnectionAsError
back/src/api/connections/connections.module.ts	Enregistrement du module browse
back/src/exceptions/api-connection.exceptions.ts	Exceptions métier (clé invalide, formulaire introuvable, etc.)

Frontend

Fichier	Rôle
front/src/pages/connections/ConnectionBrowsePage.vue	Sélection formulaire + tableau des réponses
front/src/stores/connection-browse-store.js	fetchConnection, fetchForms, fetchFormResponses, tri / pagination locale
front/src/pages/connections/ConnectionsPage.vue	Action Consulter
front/src/router/routes.js	Route browse + redirections /explore et /forms/…/responses

Dépendance Formulaires (M2M)

Fichier	Rôle
formulaires/back/src/export/export.controller.ts	GET /export/json/forms/:id/responses
formulaires/back/src/export/export.service.ts	exportFormResponsesJson → { fields, data }
formulaires/back/src/form/form.service.ts	GET /forms (clés API : type general)

4. Endpoints API (rappel)

Méthode	Chemin	Description
GET	/connections/:connectionUuid/forms	Liste des formulaires (proxy Formulaires)
GET	/connections/:connectionUuid/forms/:formUuid/responses	Réponses exportées en JSON (?formTitle= optionnel)

Réponse liste (extrait) :

{
  "items": [
    {
      "uuid": "...",
      "title": "Formulaire RH",
      "code": "RH-01",
      "publishedAt": "2026-05-01T12:00:00.000Z",
      "publicationStatus": "published"
    }
  ]
}

Réponse réponses (extrait) :

{
  "columns": [{ "name": "nom", "label": "nom", "type": "text" }],
  "rows": [{ "nom": "Alice" }],
  "total": 1,
  "loadedAt": "2026-05-19T15:41:12.508Z",
  "meta": {
    "provider": "formulaires",
    "resource": "form",
    "dataset": "responses",
    "itemId": "...",
    "itemLabel": "Formulaire RH"
  }
}

5. Règles métier implémentées

• Accès réservé aux admins (AuthGuard + AdminGuard), avec périmètre entreprise identique à BDD-114.
• Seules les connexions de type FORMULAIRES sont consultables via ce parcours.
• La clé API est déchiffrée côté serveur (getConnectionContext) ; le front n'appelle que les routes /connections/....
• Liste des formulaires : pagination curseur Formulaires (pageSize=100), filtre type=general, tri alphabétique français côté back.
• Export des réponses : format JSON { fields, data } (plus de parsing CSV côté Outil BDD).
• Pagination et tri du tableau : côté front (20 lignes par page).
• Formulaire introuvable (404 Formulaires) → message dédié + retrait de formUuid dans l'URL.
• Clé révoquée / expirée (détectée même en HTTP 500) → markConnectionAsError (status = ERROR, error_message renseigné) puis message « Clé API invalide ou révoquée. »
• URL de reprise : ?formUuid= (+ formTitle si pertinent).

6. Points de vérification

• Consulter sur une connexion active → page Parcourir la connexion, liste des formulaires chargée.
• Sélection d'un formulaire → tableau affiché, URL avec ?formUuid=.
• Tri et pagination du tableau fonctionnels.
• Formulaire inexistant → toast explicite, pas de blocage de la page.
• Clé révoquée → message clair (pas de JSON brut 500) ; retour sur /connections → badge Erreur.
• Rechargement direct de /connections/:uuid/browse?formUuid=… → formulaire présélectionné.
• Anciennes URLs /explore ou /forms/…/responses → redirection vers browse.
• Aucune clé API visible dans les requêtes réseau du navigateur.

7. Tests associés

Backend (unitaires)

• back/src/api/connections/browse/connection-browse.service.spec.ts
  • liste paginée + filtre general
  • mapping export JSON → colonnes / lignes
  • markConnectionAsError si clé invalide
• back/src/api/connections/browse/connection-browse.controller.spec.ts
  • délégation listForms / loadFormResponses
• back/src/api/connections/browse/formulaires.client.spec.ts
  • headers M2M, 401 / 403 / 404, clé révoquée en 500, réseau
• back/src/api/connections/browse/formulaires.catalog.spec.ts
  • buildCatalogUrl
• back/src/api/connections/connections.service.spec.ts
  • getConnectionContext
  • markConnectionAsError

Backend (e2e)

• back/test/e2e/connections-controller.e2e-spec.ts
  • GET /connections/:uuid/forms : 401, 200 (liste mockée)
  • GET /connections/:uuid/forms/:formUuid/responses : 404, 200 (JSON mocké)

Frontend (unitaires)

• front/src/__tests__/stores/connection-browse-store.spec.js
  • fetchConnection, fetchForms, fetchFormResponses
  • tri / pagination (sortedPaginatedRows)
  • rechargement connexion si clé invalide
• front/src/__tests__/pages/connections/ConnectionBrowsePage.spec.js
  • montage, états vides, tableau, erreurs, retour, 404
• front/src/__tests__/pages/connections/ConnectionsPage.spec.js
  • navigation Consulter → /browse
• front/src/__tests__/router/routes.spec.js
  • route browse + redirections legacy

8. Notes d'implémentation

• Parcours nommé browse (connections/browse/, store connectionBrowse) ; remplace l'ancien vocable « explorer ».
• Une seule page (ConnectionBrowsePage) : sélection + tableau (UX alignée sur la consultation des sources).
• Export JSON côté Formulaires pour éviter les problèmes CSV (multilignes, guillemets, checkpoints).
• Hors périmètre : création / renommage / suppression de connexion (BDD-114 / 116), import des réponses vers une source BDD, rotation de clé sur connexion existante.