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.
Leçon 9 sur 22 · Projet intégrateur : créer, évaluer et livrer un produit d'IAFondations du frontend
1. Choisir et délimiter le projet
2. Préparer les données et l'architecture
3. Créer un parcours utilisateur complet
4. Ajouter la fiabilité et le contrôle d'accès
5. Évaluer et améliorer
6. Déployer et exploiter
7. Préparer la présentation du portfolio
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 main
Ce que vous devez savoir
- Comment un navigateur communique avec un serveur par HTTP, dans Du navigateur au serveur : les bases.
- Pourquoi une page et son API à la même adresse n’ont pas besoin de paramètres CORS, dans Accès depuis le navigateur et CORS.
- Le backend de cette portion du produit et son format d’erreur unique, dans Fondations du backend.
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/readyaffiche"status":"ready"(état : prêt). - Un navigateur récent : Chrome, Edge, Firefox ou Safari.
Un ascenseur qui affiche l’étage
Section intitulée « Un ascenseur qui affiche l’étage »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.
Le problème : une page qui ne dit rien
Section intitulée « Le problème : une page qui ne dit rien »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.
L’idée : chaque action a des états visibles
Section intitulée « L’idée : chaque action a des états visibles »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) |
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.
Une page simple, servie par l’API
Section intitulée « Une page simple, servie par l’API »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.
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.
Une fonction pour chaque appel
Section intitulée « Une fonction pour chaque appel »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.
Le texte du serveur n’est jamais du HTML
Section intitulée « Le texte du serveur n’est jamais du HTML »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.
Conçue pour chaque personne qui l’utilise
Section intitulée « Conçue pour chaque personne qui l’utilise »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.
La page de Sam, étape par étape
Section intitulée « La page de Sam, étape par étape »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.
-
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 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. -
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é.
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. -
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.pdfFenêtre de terminal Set-Content -NoNewline warranty-cut.pdf "%PDF-1.7`n1 0 obj << /Type /Catalog >> endobj`ncut during the upload"Téléversez
warranty-cut.pdfsur 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 documentuploaded.
Accepté, mais pas encore indexé : l'état du téléversement et les décomptes. L’image est en anglais. -
Attendez un moment, sans recharger. Le tableau change seul : le processus n’a pas pu lire le fichier, et la ligne indique pourquoi.

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. -
Posez la question « Le service d’assistance est-il ouvert le 26 décembre? ».

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.
Erreurs courantes
Section intitulée « Erreurs courantes »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.

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.

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).
Sur un téléphone
Section intitulée « Sur un téléphone »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.

Votre projet
Section intitulée « Votre projet »- 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
fetchsuffisent.
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
innerHTMLavec 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érification des connaissances
Section intitulée « Vérification des connaissances »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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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
uploadedouparsing(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