Initialisation du dépôt : specs (socle plateforme, modèle de données, site vitrine) et steering

2026-10-12 11:06:57 +02:00
commit 0a33e755ff
12 changed files with 1512 additions and 0 deletions
@@ -0,0 +1,19 @@
+# Langue des échanges
+
+## Règle
+
+Toujours répondre à l'utilisateur **en français**, quelle que soit la langue de la question ou du contenu technique affiché.
+
+Cela s'applique à :
+
+- toutes les réponses et explications dans le chat ;
+- les messages de synthèse de fin de tâche ;
+- les questions de clarification posées à l'utilisateur ;
+- les messages de commit Git ;
+- les commentaires de code rédigés pour ce projet ;
+- le contenu rédactionnel des documents de spec (`requirements.md`, `design-requirements.md`, `design.md`, `tasks.md`).
+
+## Exceptions
+
+- Ne pas traduire les termes techniques, mots-clés de langage, noms d'API, identifiants de code, commandes shell ni le contenu littéral des fichiers (le code reste tel quel).
+- Les mots-clés EARS des specs (WHEN / IF / WHILE / WHERE / THE ... SHALL) restent en anglais, conformément au format.
@@ -0,0 +1,55 @@
+# Synchronisation des specs avec le code
+
+## Règle
+
+Les documents de spécification du projet sont la source de vérité à long terme. Ils DOIVENT rester alignés avec le code.
+
+Le projet sépare la spécification selon **deux axes** :
+
+- **Axe exigences** (le « quoi ») :
+  - `requirements.md` : exigences **fonctionnelles métier** au format EARS (attendu fonctionnel, mode opératoire, règles de gestion fournis par le PO business).
+  - `design-requirements.md` : exigences **techniques** dérivées (rendu visuel détaillé, API externes et URL, codes HTTP précis, délais/débounce, sécurité, cache, fallbacks, rendu cartographique et documentaire), arbitrées conjointement par le PO business et le PO IT. Ce document est organisé **en miroir** de `requirements.md` : chaque section reprend le même numéro et le même titre, suivi de « — aspects techniques ». Seules les exigences comportant effectivement des critères techniques y figurent.
+- **Axe conception** (le « comment ») :
+  - `design.md` : conception technique qui **met en œuvre** les exigences des deux documents ci-dessus (architecture, modèles de données, endpoints, composants, décisions et alternatives rejetées).
+- **Journal** :
+  - `tasks.md` : journal d'implémentation, pas une source de vérité.
+
+À chaque évolution fonctionnelle ou technique validée par l'utilisateur (« ça fonctionne », « tu peux committer »), mettre à jour les specs concernées **dans le même commit** que le changement de code, avant de committer.
+
+## Portée
+
+- `requirements.md` : mettre à jour dès qu'un comportement observable **métier** change (nouvelle fonctionnalité, modification d'un critère d'acceptation fonctionnel, nouveau terme du glossaire métier, changement de portée comme l'ajout de l'authentification).
+- `design-requirements.md` : mettre à jour dès qu'une exigence **technique** change ou est ajoutée (nouveau code HTTP, nouveau délai/débounce, nouvelle API externe, règle de sécurité, politique de cache, détail de rendu visuel). Conserver le miroir numéroté avec `requirements.md` : même numéro et même titre + « — aspects techniques ». Lorsqu'une exigence métier nouvelle ou modifiée a un pendant technique, mettre à jour les DEUX documents de façon cohérente ; ajouter tout terme technique au glossaire technique.
+- `design.md` : mettre à jour dès qu'une décision d'architecture, un modèle de données, un endpoint d'API ou un composant important change.
+- `tasks.md` : facultatif — le mettre à jour seulement si l'utilisateur le demande.
+
+> **Note sur les specs séparées** : certaines fonctionnalités disposent de leur propre spec autonome (ex. `precision-distances-km`, avec ses propres `requirements.md`/`design.md`). Lorsque le détail complet d'un sujet vit dans une spec séparée, la spec principale y renvoie par référence croisée plutôt que de dupliquer le contenu ; garder ces renvois cohérents lors d'une évolution.
+
+## Ce qui déclenche une mise à jour de spec
+
+- Nouvelle capacité (ex. aller/retour, authentification, consultation par mois).
+- Changement de contrat d'API (nouveau champ DTO, nouvel endpoint, changement de statut HTTP) → `design-requirements.md` (code HTTP) et/ou `design.md` (endpoint).
+- Nouveau modèle de données ou migration EF Core → `design.md`.
+- Changement de règle métier (ex. tranches de barème multiples, distance effective doublée) → `requirements.md`.
+- Nouveau détail technique observable (délai, débounce, URL d'API, en-tête, fallback, rendu) → `design-requirements.md`.
+- Changement de portée du produit (ex. passage de mono-utilisateur sans compte à compte unique authentifié).
+
+## Ce qui ne déclenche PAS forcément une mise à jour
+
+- Ajustements purement cosmétiques (couleurs, espacements) sans exigence associée.
+- Refactorisations internes sans effet observable et sans changement de décision d'architecture.
+
+## Format
+
+- `requirements.md` et `design-requirements.md` : conserver le format EARS (WHEN / IF / WHILE / WHERE / THE ... SHALL). Numéroter les nouvelles exigences à la suite. Conserver le miroir numéroté entre les deux documents. Ajouter au glossaire approprié (métier ou technique) tout nouveau terme.
+- `design.md` : conserver la structure existante (overview, périmètre, contraintes, décisions d'architecture, modèles, endpoints, composants, propriétés). Documenter les décisions et les alternatives rejetées.
+- Valider le format avec l'outil de validation de spec après édition.
+
+## Workflow au moment du commit
+
+1. Implémenter le changement de code et le faire valider par l'utilisateur.
+2. Mettre à jour les specs concernées pour refléter le changement :
+   - comportement métier → `requirements.md` ;
+   - détail technique observable → `design-requirements.md` (en conservant le miroir avec `requirements.md`) ;
+   - architecture / modèle / endpoint / composant → `design.md`.
+3. Committer code + specs ensemble, avec un message décrivant les deux.
@@ -0,0 +1,33 @@
+# Structure du projet
+
+## Vue d'ensemble
+
+Le dossier racine `schotzimmo` est l'espace de travail global du projet. Il réunit, au même endroit, la **spécification**, les **documents de travail** propres à l'utilisateur et le **code applicatif**. Cette séparation permet de mener la phase de spec et le développement sans les mélanger.
+
+## Organisation des dossiers
+
+### Racine `schotzimmo/`
+
+Espace de travail du projet. Sert de point d'entrée et contient les dossiers décrits ci-dessous. On n'y place pas directement de code applicatif.
+
+### `.kiro/`
+
+Dossier de configuration de l'environnement de spec.
+
+- `.kiro/specs/` : documents de spécification du projet (source de vérité à long terme). Chaque fonctionnalité ou socle dispose de son sous-dossier (ex. `socle-plateforme/`). Un sous-dossier préfixé par `_` regroupe des éléments transverses (ex. `_data-model/`).
+- `.kiro/steering/` : fichiers de steering qui cadrent la collaboration (langue, workflow, synchronisation des specs, et le présent document de structure).
+
+### Documents de travail de l'utilisateur
+
+L'utilisateur peut créer, sous la racine, d'autres sous-dossiers pour ses **documents personnels** en lien avec le projet (notes, réflexions, références, maquettes, etc.). Ces documents lui sont propres et ne font pas partie de la spec officielle ni du code applicatif.
+
+### `App/`
+
+Sous-dossier dédié au **développement de la solution web** (frontend et backend). C'est ici que vit le code applicatif. La structure interne de `App/` (découpage frontend/backend, modules, etc.) sera précisée au fur et à mesure de la conception.
+
+## Règles d'emplacement
+
+- La spec vit exclusivement dans `.kiro/specs/`.
+- Le cadrage de la collaboration vit dans `.kiro/steering/`.
+- Le code applicatif vit exclusivement dans `App/`.
+- Les documents de travail personnels de l'utilisateur vivent dans des sous-dossiers dédiés à la racine, distincts de `.kiro/` et de `App/`.
@@ -0,0 +1,20 @@
+# Méthode de collaboration
+
+## Valider l'approche avant de coder
+
+Ne jamais commencer à écrire ou modifier du code applicatif tant que l'approche n'a pas été exposée et explicitement validée par l'utilisateur.
+
+Pour toute évolution ou correction fonctionnelle/technique :
+
+1. D'abord décrire l'orientation envisagée (structure, impacts, choix et alternatives), de façon concise.
+2. Attendre la validation explicite de l'utilisateur. Le signal convenu est le mot « code » : tant qu'il n'est pas donné, rester en discussion et ne pas éditer de fichier de code.
+3. Une fois « code » reçu, implémenter puis vérifier (build/tests).
+
+## Exceptions (ne nécessitent pas le signal « code »)
+
+- Les actions de configuration ou de documentation explicitement demandées par l'utilisateur (ex. ajout/mise à jour d'un fichier de steering, d'une spec, d'un README) quand la demande est sans ambiguïté.
+- Les opérations de lecture, recherche, build, test ou diagnostic qui ne modifient pas le code applicatif.
+
+## Lancement de l'environnement de développement
+
+C'est l'utilisateur qui lance le serveur de développement (`./run-dev.sh`). Ne pas le démarrer automatiquement ; se contenter de signaler quand un redémarrage est nécessaire (ex. changement backend).