Aller au contenu
English

Fondations du frontend

  • Leçon 9
  • 100 min
  • Module 3 : Créer un parcours utilisateur complet

Où nous en sommes

Dans la leçon précédente, nous avons fait fonctionner un parcours sur le serveur : téléversement, état, question et réponse. Mais Grace ne peut pas utiliser un terminal pour l'essayer. Dans cette leçon, nous lui donnons une page simple qui montre chaque état de chaque action : en attente, terminé, vide et erreur, comme un ascenseur qui affiche l'étage pendant que vous attendez.

Ce que vous saurez faire

Permettez à Grace d’utiliser cette portion du produit sans terminal. Une page simple téléverse un document, montre son état d’indexation et permet de poser une question. Elle affiche la réponse, une absence de réponse honnête ou une erreur claire.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 100 minutes

Ce que vous devez savoir

Le cours Architecture frontend et performance des applications d’IA est prévu, mais pas encore publié. Cette leçon n’en a pas besoin. Elle utilise une page HTML, un fichier CSS et un fichier JavaScript, sans cadriciel ni étape de construction. Elle explique chaque partie qu’elle utilise.

Ce qu’il vous faut sur votre ordinateur

  • Votre projet de la dernière leçon, avec les substituts (EMBEDDER=hash, ANSWER_PROVIDER=mock), l’ensemble chargé et l’API en marche : curl -s http://127.0.0.1:8000/ready affiche "status":"ready" (état : prêt).
  • Un navigateur récent : Chrome, Edge, Firefox ou Safari.

Vous appuyez sur le bouton d’un ascenseur. Le bouton s’allume, et un écran montre l’étage de l’ascenseur pendant son arrivée. Vous attendez calmement, car vous voyez que quelque chose se passe.

Imaginez maintenant un bouton d’ascenseur sans lumière ni écran. Vous appuyez dessus, et rien ne semble changer. La plupart des gens appuient encore, puis encore. Certains prennent l’escalier, même si l’ascenseur était en route.

Supposons que la page contient seulement un formulaire et une zone de résultat. Grace téléverse les heures des Fêtes, ne voit aucun changement et clique encore sur Upload (téléverser). Le deuxième téléversement produit une erreur, car le fichier existe déjà : vous avez vu cette erreur 409 dans la dernière leçon. Le premier clic a fonctionné, mais la page ne l’a pas indiqué.

Supposons maintenant que l’API s’arrête pendant que Grace garde la page ouverte. Elle pose une question, et la requête du navigateur échoue avant l’arrivée d’une réponse. Une page qui attend seulement une réponse n’affiche rien du tout. Pour Grace, les deux cas semblent identiques : une page qui ne fonctionne pas.

Chaque action sur la page passe par quelques états, et la page montre chacun d’eux. Attente : le bouton est désactivé, et une ligne indique ce qui se passe (« Recherche dans les documents… »). Terminé : la réponse, ou le nouveau document dans le tableau. Vide : un résultat réel qui ne contient rien, comme « Aucune réponse dans les documents ». Erreur : ce qui a échoué, en mots. Si l’API a répondu, le code et l’identifiant de requête suivent. Sam peut retrouver cet identifiant dans le journal.

On appelle souvent ces états les états de chargement, de résultat vide et d’erreur d’une page. Une page qui montre seulement le résultat réussi présente un état sur quatre. Voici les états du formulaire Ask (poser une question), avec le texte exact qu’affiche app.js :

État Ce que la personne voit Ce que fait le code
Prêt le formulaire rien pour l’instant
Attente « Searching the documents… » (recherche dans les documents); le bouton Ask est désactivé button.disabled = true pendant l’exécution de fetch
Réponse « Answer » (réponse), la réponse, les affirmations avec leurs citations, le fournisseur et le temps showAnswer(data.answer)
Aucune réponse « No answer in the documents » (aucune réponse dans les documents) dans un cadre ambré la même fonction, avec answerable: false
Erreur le message, puis « (code …, request …) » (code…, requête…) showError(target, problem)
Un diagramme des états du formulaire Ask. Depuis l'état Prêt, Ask mène à Attente, où la ligne indique une recherche dans les documents et le bouton est désactivé. Depuis Attente, une réponse 200 qui peut répondre mène à Réponse avec ses preuves. Une réponse 200 qui ne peut pas répondre mène à Aucune réponse dans les documents. Une erreur 4xx, 5xx ou une absence de connexion mène à Erreur, avec le message, le code et l'identifiant de requête. Depuis chacun de ces trois états, poser une autre question ramène à Attente.
Les cinq états du formulaire Ask. Le formulaire de téléversement suit le même modèle : téléversement en cours, puis nouvelle ligne dans le tableau ou erreur.
Description textuelle du diagramme

Le formulaire commence à l’état prêt. Quand la personne pose une question, il attend. La ligne indique « Searching the documents… » et le bouton est désactivé, pour empêcher un deuxième clic d’envoyer une deuxième requête. Il aboutit ensuite à l’un de trois états : une réponse avec ses preuves, « No answer in the documents » ou une erreur. L’erreur affiche le message, le code et l’identifiant de requête. Depuis chacun de ces états, la personne peut poser une autre question.

Le téléversement a une quatrième étape, car l’API répond avant la fin de l’indexation. Le tableau doit montrer l’état de chaque document et le modifier sans rechargement. La page redemande les documents à l’API toutes les 1,5 secondes tant qu’un document est uploaded (téléversé) ou parsing (en analyse). Quand tous sont indexed (indexés) ou failed (en échec), elle cesse de demander. C’est l’interrogation périodique (polling) : répéter une demande à intervalle fixe. Elle coûte une petite requête toutes les 1,5 secondes par page ouverte, seulement pendant une indexation. Un serveur qui envoie chaque changement à la page demanderait moins de requêtes, mais plus de code des deux côtés. Pour quelques téléversements par jour, l’interrogation périodique suffit.

La page comprend trois fichiers dans doc_assistant/static/ : index.html (65 lignes), app.css (37 lignes) et app.js (186 lignes). L’API les sert à /app/, et / y dirige le navigateur. La page et l’API ont donc la même adresse. Le navigateur envoie ainsi ses requêtes sans paramètres CORS. Dans le module 4, cette même adresse permet aussi au témoin (cookie) de connexion de fonctionner.

Pourquoi aucun cadriciel? Le cours sur le frontend n’est pas encore publié. Un cadriciel ajoute une étape de construction, un deuxième gestionnaire de paquets et ses propres erreurs. Une page avec fetch assure tout le parcours. Son coût : vous écrivez vous-même les petits éléments, comme el(), qui crée un élément. La page devient aussi plus difficile à modifier à mesure qu’elle grandit. Pour une portion du produit qui comporte cinq actions, cela convient.

Deux colonnes. À gauche, les parties de la page : l'en-tête avec votre identité, la liste des boutiques et votre rôle; le formulaire Ask avec la réponse et les preuves; le formulaire de téléversement avec son état; le tableau des documents avec ses décomptes. À droite, l'appel d'API derrière chaque partie : GET /auth/session et GET /v1/me au chargement; les adhésions dans GET /v1/me; POST /v1/tenants/{t}/answers pour Ask; POST /v1/tenants/{t}/documents pour Upload; GET /v1/tenants/{t}/documents au chargement, après un téléversement et toutes les 1,5 secondes pendant l'indexation d'un document. Un encadré en dessous : chaque appel passe par une seule fonction, api(), qui retourne le JSON ou une erreur avec son message, son code et son identifiant de requête.
Chaque partie de la page et l'appel d'API qui la soutient. Tous les appels passent par la même fonction.
Description textuelle du diagramme

L’en-tête appelle GET /auth/session et GET /v1/me au chargement de la page et montre sous quelle identité vous agissez. La liste des boutiques vient des adhésions dans /v1/me. Ask envoie POST /v1/tenants/{t}/answers. Upload envoie POST /v1/tenants/{t}/documents. Le tableau des documents appelle GET /v1/tenants/{t}/documents au chargement, après un téléversement et toutes les 1,5 secondes pendant une indexation. Chaque appel passe par api(), qui retourne le JSON ou une erreur avec son message, son code et son identifiant de requête.

Chaque requête de la page passe par une seule fonction, api(). Elle transforme chaque échec en un même type d’objet d’erreur, ApiProblem. Cet objet contient les champs code, message et request_id du format d’erreur unique du backend :

async function api(path, options = {}) {
const headers = { Accept: 'application/json', ...(options.headers || {}) };
if (options.method && options.method !== 'GET' && state.csrf) headers['X-CSRF-Token'] = state.csrf;
let response;
try {
response = await fetch(path, { credentials: 'same-origin', ...options, headers });
} catch {
throw new ApiProblem(0, { code: 'network', message: 'The assistant cannot be reached. Is the API running?' });
}
const body = await response.json().catch(() => ({}));
if (!response.ok) throw new ApiProblem(response.status, body);
return body;
}

Le catch autour de fetch correspond au deuxième cas du problème décrit plus haut. Quand l’API ne répond pas du tout, fetch échoue avant toute réponse. La page l’indique maintenant en mots. La ligne CSRF ne fait encore rien : le module 4 ajoute le jeton.

Vous lisez une lettre à voix haute à un ami. La lettre dit : « Donnez 100 $ à la personne qui lit. » Vous lisez la phrase sans donner d’argent à personne. La lettre est quelque chose à lire, pas un ordre à suivre.

La page doit traiter le texte du serveur de la même façon. Le titre d’un document vient de son fichier, et toute personne autorisée à téléverser peut le choisir. Supposons qu’un titre soit <img src=x onerror=alert(1)>. Une page qui insère ce titre comme HTML (innerHTML) fait exécuter son code par le navigateur, dans la page de Grace. Cette attaque est une injection de script intersites (cross-site scripting). Il en va de même pour une réponse : un modèle peut répéter le texte d’un passage. La note Northwind de Bramble cache déjà une instruction.

app.js place tout texte du serveur sur la page avec textContent, par l’intermédiaire de el(). Le navigateur affiche alors les caractères <img src=x onerror=alert(1)> comme du texte et n’exécute rien. Un test maintient cette règle : test_server_text_is_never_put_on_the_page_as_html échoue si innerHTML ou insertAdjacentHTML apparaît dans app.js.

La page utilise du HTML simple pour ce que HTML fait bien. Chaque champ a un <label>. Un lecteur d’écran peut ainsi le nommer, et un clic sur l’étiquette sélectionne le champ. Les lignes d’état ont role="status" et aria-live="polite". Un lecteur d’écran lit donc « Searching the documents… » et la réponse quand elles apparaissent. Le tableau a une légende, le focus a un contour visible et les couleurs suivent le thème clair ou sombre du système. Sous 40rem, le tableau cache sa colonne « In force » (en vigueur), pour que la page convienne à un téléphone. Sans JavaScript, la page indique qu’elle en a besoin et que l’API fonctionne sans lui.

Le parcours de Grace, avec les substituts de la dernière leçon. Chaque image est une vraie capture de la page en marche. Le fichier .docx et le PDF tronqué sont fabriqués pour le test.

  1. Avec l’API en marche, ouvrez http://127.0.0.1:8000/app/ dans votre navigateur. Sam agit dans Larkfield, la boutique associée à son adhésion.

    La page sur une largeur de 1 280 pixels. L'en-tête indique Document assistant (assistant documentaire), Practice mode : you act as Sam (mode pratique : vous agissez en tant que Sam). En dessous : la liste des boutiques avec Larkfield et Your role : staff (votre rôle : personnel); le formulaire Ask a question (poser une question) avec un champ de question, un champ de date et un bouton Ask; la section Documents avec un sélecteur de fichier, trois choix de personnes autorisées à le lire, un bouton Upload, la ligne 37 documents (37 indexed) (37 documents, 37 indexés) et le haut du tableau des documents.
    La page au chargement, avec les substituts : mode pratique, boutique et rôle, formulaire Ask, formulaire de téléversement et tableau des documents. L’image est en anglais.
  2. Téléversez encore holiday-hours.md. L’API répond 409 conflict (conflit), et la page affiche le message, le code et l’identifiant de requête. Rien n’est ajouté.

    La section Documents après le téléversement de holiday-hours.md. Sous le bouton Upload, un encadré rouge indique que la version 1 de holiday-hours existe déjà. Il demande de téléverser une nouvelle version ou de supprimer d'abord l'ancienne. Le code est conflict et l'identifiant de requête est 7d5a885962ad44af. En dessous : 37 documents, tous indexés.
    L'état d'erreur du téléversement : le message de l'API, puis son code et son identifiant de requête. L’image est en anglais.
  3. Créez un PDF tronqué au milieu, comme si le téléversement s’était arrêté. Il est fabriqué pour ce test.

    Fenêtre de terminal
    printf '%%PDF-1.7\n1 0 obj << /Type /Catalog >> endobj\ncut during the upload' > warranty-cut.pdf

    Téléversez warranty-cut.pdf sur la page. L’API l’accepte (202), car un PDF tronqué passe les vérifications d’entrée. La page indique que l’indexation commence, et les décomptes au-dessus du tableau montrent un document uploaded.

    La section Documents après le téléversement d'un PDF tronqué. Une ligne verte indique que Warranty cut est téléversé et que l'indexation commence; le tableau montre son état. En dessous : 38 documents, dont 37 indexés et 1 téléversé.
    Accepté, mais pas encore indexé : l'état du téléversement et les décomptes. L’image est en anglais.
  4. Attendez un moment, sans recharger. Le tableau change seul : le processus n’a pas pu lire le fichier, et la ligne indique pourquoi.

    Une ligne du tableau des documents : Warranty cut, warranty-cut.pdf, staff (personnel), version 1, en vigueur depuis le 11 octobre 2026, état failed en rouge. La raison indique que ce fichier n'est pas un PDF lisible (PdfStreamError).
    La ligne en échec, avec la raison donnée par le processus. L'interrogation périodique s'est arrêtée, car aucun document n'est encore en cours d'indexation. L’image est en anglais.
  5. Posez la question « Le service d’assistance est-il ouvert le 26 décembre? ».

    Le formulaire Ask a question avec la question demandant si le service d'assistance est ouvert le 26 décembre. En dessous, la zone de réponse indique que, le 24 décembre et le 31 décembre, il est ouvert de 9 h à 14 h. Sous Evidence (preuves), une affirmation avec la citation Help desk holiday hours (heures des Fêtes du service d'assistance), Short days (journées écourtées), version 1. La dernière ligne : mock : mock, 4 ms et un identifiant de trace.
    Une réponse du simulateur : le bon format, une vraie citation et l'étiquette mock (simulé). Il a copié le passage « Short days » et ne répond donc pas à la question sur le 26 décembre. L’image est en anglais.

Erreur courante

L'API s'est arrêtée pendant que la page était ouverte

Symptôme : vous posez une question, et la page indique qu’elle ne peut pas joindre l’assistant et demande si l’API fonctionne.

Le formulaire Ask a question avec une question. Sous le bouton Ask, un encadré rouge indique que l'assistant est injoignable et demande si l'API fonctionne.
Sam a arrêté l'API, puis posé une question : l'état d'erreur sans connexion. L’image est en anglais.

Cause : le processus de l’API s’est arrêté, par exemple après une erreur au démarrage ou après Ctrl+C dans son terminal. fetch ne reçoit aucune réponse.

Solution : redémarrez l’API avec fastapi dev doc_assistant/main.py, puis posez de nouveau la question. La page conserve la question, pour éviter de la saisir deux fois.

Erreur courante

La page indique « Loading… » et rien d'autre

Symptôme : l’en-tête indique « Loading… » (chargement), et les formulaires ne font rien.

La page avec JavaScript désactivé. L'en-tête indique Loading…. Un encadré rouge en dessous explique que cette page a besoin de JavaScript et que l'API fonctionne sans lui : voir /docs. Les formulaires sont affichés, et le tableau des documents est vide.
La même page avec JavaScript désactivé dans le navigateur. L’image est en anglais.

Cause : JavaScript est désactivé dans votre navigateur, ou app.js n’a pas été chargé. Si JavaScript est désactivé, la page l’indique sur une ligne rouge. Si app.js manque, ouvrez les outils de développement du navigateur (F12), onglet Console ou Network (réseau) : app.js a l’état 404.

Solution : activez JavaScript pour 127.0.0.1, ou vérifiez que doc_assistant/static/app.js existe. Vous pouvez toujours utiliser l’API sans la page : http://127.0.0.1:8000/docs liste tous les points de terminaison.

Erreur courante

Vous avez modifié app.js, mais la page n'a pas changé

Symptôme : vous modifiez app.js ou app.css, rechargez et voyez l’ancien comportement.

Cause : le navigateur a gardé l’ancien fichier dans son cache. L’API envoie Cache-Control: no-store pour ses données sous /v1/, donc les données ne sont jamais mises en cache. Les fichiers de la page peuvent toutefois l’être.

Solution : rechargez sans le cache : Ctrl+Shift+R (Windows, Linux) ou Cmd+Shift+R (macOS).

Grace consulte la page sur son téléphone, avec le thème sombre. Le code n’a rien de particulier pour cela. Le CSS contient une règle pour les écrans étroits et un ensemble de couleurs pour le thème sombre.

La page sur un écran étroit de téléphone avec le thème sombre : fond sombre, texte clair et bouton Ask bleu pâle. L'en-tête, la boutique et le rôle, la question demandant si le service d'assistance est ouvert le 26 décembre, et le début de la réponse simulée avec ses preuves.
La même réponse sur un écran de 390 pixels de large, avec le thème sombre. L’image est en anglais.
  • Parcours standard. Utilisez la page pour tout le parcours : téléversez votre propre document, suivez son état, posez deux questions et provoquez une erreur. Ensuite, essayez la page avec le clavier seulement (Tab, Shift+Tab, Enter, barre d’espacement). Vous devez pouvoir atteindre et utiliser chaque commande.
  • Parcours avec votre propre idée. Créez la page de votre parcours unique. Gardez les quatre règles de cette leçon : chaque action a ses états d’attente, de réussite, de résultat vide et d’erreur; une seule fonction fait tous les appels et gère le format d’erreur unique; tout texte du serveur s’affiche comme du texte, jamais comme du HTML; chaque champ a une étiquette. Un fichier HTML et fetch suffisent.

Preuves à conserver. Des captures d’écran de votre page dans chaque état : chargée, en attente ou en cours d’indexation, réussite, résultat vide (« aucune réponse »), erreur et largeur de téléphone. Enregistrez-les dans docs/evidence/m03-page/. Ajoutez une ligne par capture dans docs/evidence/README.md pour décrire ce qu’elle montre. Votre scénario de démo du module 7 les utilise.

Liste de vérification

  • Chaque action affiche un état d’attente, et son bouton est désactivé pendant l’attente.
  • L’état d’un téléversement change sur la page sans rechargement. La page cesse les demandes quand aucune indexation n’est en cours.
  • Chaque erreur affiche le message, le code et l’identifiant de requête, même quand l’API est inaccessible.
  • Aucun innerHTML avec du texte du serveur.
  • Chaque commande fonctionne avec le clavier, et chaque champ a une étiquette.
  • La page tient sur un écran de téléphone.

Vérifiez votre compréhension

Grace clique deux fois sur Upload (téléverser), car la page n'affiche rien après le premier clic. Nommez les deux états que la page doit afficher pour éviter cela, et ce que le code fait dans chacun.

Afficher la réponse

L’état d’attente : dès qu’elle clique, la ligne affiche « Uploading… » (téléversement en cours) et le bouton est désactivé (button.disabled = true). Un deuxième clic n’envoie donc rien. L’état de réussite : quand l’API répond 202, la ligne indique que le téléversement a réussi et que l’indexation commence. Le tableau affiche le nouveau document avec son état. Si l’API refuse le fichier, l’état d’erreur affiche plutôt le message, le code et l’identifiant de requête.

Vérifiez votre compréhension

Prédisez : un membre téléverse un document dont le titre est <b>Returns</b>. Qu'affiche le tableau des documents, et pourquoi?

Afficher la réponse

Le tableau affiche les caractères <b>Returns</b>, avec les chevrons, et non le mot Returns (retours) en gras. app.js place tout texte du serveur sur la page avec textContent. Le navigateur affiche donc du texte et ne le lit jamais comme du HTML. Cela empêche un titre comme <img src=x onerror=…> d’exécuter du code dans la page d’un autre membre.

Vérifiez votre compréhension

Pourquoi la page redemande-t-elle les documents toutes les 1,5 secondes seulement pendant qu'un document est téléversé ou analysé, plutôt qu'en permanence?

Afficher la réponse

L’interrogation périodique sert à montrer un changement que la page ne peut pas voir seule : un document passant de uploaded (téléversé) à indexed (indexé) ou failed (échec). Quand tous les documents sont indexés ou en échec, rien ne peut changer sans un nouveau téléversement. Des requêtes supplémentaires ne feraient donc qu’ajouter du travail à l’API. La page redemande les documents après chaque téléversement, ce qui relance l’interrogation périodique au besoin.

Récapitulatif

  • Chaque action a des états visibles : attente, réussite, résultat vide et erreur. Une page qui montre seulement le résultat réussi pousse les gens à cliquer de nouveau.
  • La page se compose de trois fichiers simples, servis par l’API à /app/ : même adresse, aucun réglage CORS, aucune étape de construction.
  • Une seule fonction, api(), fait tous les appels et transforme chaque défaillance en message, code et identifiant de requête. Cela vaut aussi quand l’API est inaccessible.
  • L’interrogation périodique affiche l’état d’indexation : toutes les 1,5 secondes, seulement lorsqu’un document est uploaded ou parsing (en cours d’analyse).
  • Le texte du serveur s’affiche sur la page avec textContent, jamais comme du HTML. Un test le vérifie.

Ensuite, les éléments simulés disparaissent : récupération réelle, réponses enregistrées d’un vrai modèle, citations vérifiées dans le code et trace de chaque question.

Leçon suivante : Intégrer la récupération