# BRIEF FOR ARCHITECT ## [Intent] Permettre à un utilisateur de retrouver les conditions météorologiques passées, heure par heure, pour n'importe quelle commune de France, via une page web unique, simple et sans inscription. L'utilisateur saisit une commune, choisit une période passée, et obtient un tableau horaire lisible avec température, précipitations, humidité, vent et description des conditions — le tout en fuseau horaire français. --- ## [User Goals] - **Retrouver la météo d'un jour précis dans le passé** (mariage, course sportive, voyage, événement marquant) sans compétence technique. - **Obtenir une granularité horaire**, pas un simple résumé journalier. - **Identifier rapidement une commune française** grâce à une recherche par nom avec auto-complétion. - **Comprendre la nature des données** affichées (réanalyse vs. station locale) pour ajuster ses attentes. - **Accéder au résultat immédiatement**, sans inscription, sans configuration, depuis un mobile ou un desktop. --- ## [User Flows] ### Flow principal — Consultation météo historique 1. L'utilisateur arrive sur la page unique de l'application. 2. Il saisit le début d'un nom de commune dans le champ de recherche. 3. Une liste de suggestions apparaît (auto-complétion : nom de commune + département). 4. Il sélectionne une commune dans la liste. 5. Un sélecteur de période apparaît (ou devient actif) avec deux champs : date de début et date de fin. - La plage de dates disponibles est indiquée clairement (date la plus ancienne disponible → hier). - Si l'utilisateur tente de sélectionner une date hors plage, un message explicite l'en informe. 6. Il choisit une date de début et une date de fin (maximum 31 jours d'écart). - Si l'écart dépasse 31 jours, un message explicite l'informe de la limite. 7. Il lance la recherche (bouton ou action automatique après sélection complète). 8. Un état de chargement s'affiche pendant la récupération des données. 9. Le tableau des résultats s'affiche : une ligne par heure, avec les colonnes météo. 10. L'utilisateur consulte les données. Il peut modifier la commune ou la période pour relancer une recherche. ### Points de décision - **Étape 3 :** si aucune commune ne correspond à la saisie → message "Aucune commune trouvée". - **Étape 6 :** si la période dépasse 31 jours → message "La période est limitée à 31 jours maximum". - **Étape 6 :** si une date est dans le futur → message "Seules les dates passées sont disponibles". - **Étape 8 :** si l'API météo est indisponible → message d'erreur explicite (voir états d'erreur). ### États de l'interface | État | Comportement | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Vide (initial)** | Champ de recherche commune visible. Sélecteur de dates désactivé ou masqué. Aucun tableau. | | **Commune sélectionnée** | Le sélecteur de dates devient actif. La plage disponible est affichée. | | **Période valide sélectionnée** | Le bouton de recherche est actif (ou la recherche se lance automatiquement). | | **Chargement** | Indicateur visuel de chargement. Le formulaire reste visible mais non modifiable. | | **Résultats affichés** | Tableau horaire visible. Le formulaire reste accessible pour modifier les paramètres. | | **Erreur API commune** | Message : "Le service de recherche de communes est temporairement indisponible. Réessayez dans quelques instants." | | **Erreur API météo** | Message : "Le service de données météo est temporairement indisponible. Réessayez dans quelques instants." | | **Aucun résultat commune** | Message : "Aucune commune trouvée pour cette recherche." | | **Période invalide** | Message contextuel précisant le problème (trop longue, date future, date antérieure à la limite). | --- ## [Functional Needs] - **FN1** — L'utilisateur peut rechercher une commune française par son nom. La recherche offre une auto-complétion affichant le nom de la commune et son département. - **FN2** — L'utilisateur peut sélectionner une commune parmi les suggestions pour la définir comme lieu de recherche. - **FN3** — L'utilisateur peut choisir une date de début et une date de fin pour définir la période de consultation. La période maximale est de 31 jours. - **FN4** — La plage de dates disponibles (date la plus ancienne → veille du jour actuel) est affichée clairement pour guider la sélection. - **FN5** — L'application affiche les résultats sous forme d'un tableau avec une ligne par heure et les colonnes suivantes : date/heure, température, précipitations, humidité, vitesse du vent, description des conditions météo. - **FN6** — Toutes les heures affichées sont en fuseau horaire Europe/Paris. - **FN7** — Une note de transparence est visible sur la page, expliquant en termes simples que les données proviennent d'une reconstitution par modèle météorologique (réanalyse) et non d'une station locale, et ce que cela implique pour la précision. - **FN8** — En cas d'erreur (API indisponible, requête invalide, période hors limites), un message d'erreur explicite et compréhensible est affiché. Pas de message générique. - **FN9** — L'interface est responsive et utilisable sur desktop comme sur mobile. - **FN10** — Les communes d'outre-mer (DOM-TOM) sont incluses dans la recherche si elles sont couvertes par l'API météo. - **FN11** — L'application fonctionne en page unique, sans navigation entre plusieurs vues. - **FN12** — Aucune inscription ni authentification n'est requise. --- ## [Acceptance Criteria] - **AC1** — En saisissant au moins 2 caractères d'un nom de commune, une liste de suggestions pertinentes (nom + département) apparaît en moins de temps raisonnable. - **AC2** — Après sélection d'une commune et d'une période valide (≤ 31 jours, dates passées, dans la plage disponible), un tableau horaire s'affiche avec les données météo. - **AC3** — Le tableau contient une ligne par heure sur toute la période sélectionnée, avec au minimum : date/heure, température (°C), précipitations (mm), humidité (%), vitesse du vent (km/h), description des conditions. - **AC4** — Toutes les heures affichées correspondent au fuseau Europe/Paris. - **AC5** — Si la période demandée dépasse 31 jours, un message d'erreur explicite s'affiche avant toute requête météo. - **AC6** — Si une date sélectionnée est dans le futur, un message d'erreur explicite s'affiche. - **AC7** — Si une date sélectionnée est antérieure à la limite historique de l'API, un message d'erreur explicite s'affiche. - **AC8** — Si l'API de communes ou l'API météo est indisponible, un message d'erreur explicite et non générique s'affiche. - **AC9** — La note de transparence sur la réanalyse est visible sans action de l'utilisateur (pas uniquement dans un tooltip caché). - **AC10** — L'interface est lisible et utilisable sur un écran mobile (largeur 360px minimum). - **AC11** — L'application est accessible et utilisable sans inscription. --- ## [Constraints] - **Données communes :** API geo.api.gouv.fr (publique, gratuite, sans clé). - **Données météo :** API Open-Meteo Historical (publique, gratuite, sans clé). - **Aucune donnée stockée côté serveur** (pas de base de données propre). - **Budget API : zéro.** Aucun service payant. - **Hébergement :** auto-hébergé pour le MVP, migration Vercel envisagée ensuite. - **Période max par requête :** 31 jours. - **Fuseau horaire d'affichage :** Europe/Paris. - **Page unique** — pas de routeur ni de navigation multi-pages. - **Performance :** un mécanisme de cache côté serveur est nécessaire pour limiter les appels API et garantir la réactivité. --- ## [Non-Goals] - Graphiques (courbes de température, histogrammes de précipitations). - Résumés journaliers (min/max/cumuls). - URLs partageables avec paramètres pré-remplis. - Comparaison entre deux périodes ou deux années. - Export des données (CSV, JSON). - Gestion de comptes utilisateurs. - Historique des recherches. - Nom de domaine dédié. --- ## [Open Decisions] - **OD1** — Quel mécanisme de cache côté serveur adopter ? (durée de vie, stratégie d'invalidation, stockage en mémoire vs. fichier) - **OD2** — Faut-il un backend applicatif (Node, Python…) ou le MVP peut-il fonctionner en full front-end avec appels API directs depuis le navigateur ? Le brief mentionne un cache serveur, ce qui implique un backend. - **OD3** — Quelle stratégie pour la description textuelle des conditions météo ? L'API Open-Meteo renvoie des codes WMO — la traduction en texte français lisible est à décider techniquement. - **OD4** — Quel comportement adopter pour les communes d'outre-mer dont le fuseau horaire n'est pas Europe/Paris ? Afficher en heure locale du territoire ou toujours en Europe/Paris ? - **OD5** — Quel seuil de caractères déclenche l'auto-complétion (2, 3…) ? Et quel debounce appliquer pour limiter les appels API ? --- ## [Assumptions] - **A1** — L'API geo.api.gouv.fr fournit les coordonnées GPS (latitude/longitude) de chaque commune avec une précision suffisante pour interroger l'API météo. - **A2** — L'API Open-Meteo Historical couvre la France métropolitaine avec une granularité horaire et une profondeur historique d'au moins plusieurs décennies. - **A3** — Le volume d'utilisation initial sera faible et ne déclenchera pas les limites de débit des APIs gratuites. - **A4** — L'affichage sous forme de tableau est le format le plus lisible et le plus adapté pour un MVP. - **A5** — Les communes d'outre-mer couvertes par Open-Meteo seront incluses automatiquement, sans traitement spécifique. - **A6** — Un seul jeu de données horaires par requête est suffisant (pas de comparaison ni d'agrégation). --- ## [Questions to Architect] - **QA1** — Backend léger (Node/Python) avec cache, ou front-end pur avec appels API directs ? Le brief demande un cache serveur — quel compromis entre simplicité MVP et robustesse ? - **QA2** — Comment gérer la traduction des weather codes WMO en descriptions françaises lisibles ? Table de correspondance côté front ou côté back ? - **QA3** — Quelle est la profondeur historique réelle d'Open-Meteo Historical ? Y a-t-il une API pour la détecter dynamiquement ou faut-il la coder en dur ? - **QA4** — Quel format de date/heure pour le tableau ? (ex : "Lun 15/06/2024 14h00" vs. "2024-06-15 14:00") - **QA5** — Pour les DOM-TOM, faut-il prévoir un affichage en heure locale du territoire ou rester en Europe/Paris ? - **QA6** — Faut-il prévoir un mécanisme de retry automatique en cas d'échec temporaire d'API, ou laisser l'utilisateur relancer manuellement ? - **QA7** — Structure du projet : mono-repo front+back, ou front statique séparé ? Quel hébergement auto-hébergé est prévu (Docker, PM2, simple serveur statique…) ?