Docs: update README/ARCHITECTURE/GUIDE for all current features

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Florian Flahaut

README.md

@@ -9,18 +9,25 @@ rien au jardinage.
 - **Ce mois-ci** — ce qu'il faut semer / planter / récolter maintenant, avec
   filtres cliquables par action.
 - **Calendrier de l'année** — grille plantes × 12 mois (semis, plantation,
-  récolte), filtrable par catégorie et par action.
+  récolte), filtrable par catégorie et par action, **imprimable**.
 - **Fiches plantes** — 38 plantes (légumes, fruits, aromates) : exposition,
-  sol, arrosage, levée, espacement, ravageurs, rotation, compagnonnage.
-- **Mon jardin** — suivi personnel des plantations avec rappels de tâches du
-  mois (récolte, soins, arrosage) et **conseils d'arrosage selon la météo
-  locale** (Open-Meteo).
+  sol, arrosage, levée, espacement, ravageurs, rotation, compagnonnage,
+  **quantité conseillée** et **liens d'achat** (comparateur de prix).
+- **Mon jardin** — suivi des plantations avec **récolte prévisionnelle** (selon
+  la date de plantation), **tâches du mois cochables**, et **conseils
+  d'arrosage selon la météo locale** (Open-Meteo, par géoloc ou par ville).
 - **Journal de jardin** — récoltes, semis, observations et traitements datés,
   avec quantités.
-- **Plan du potager** — dessin des carrés et placement des plantes, avec
-  détection des voisinages déconseillés (compagnonnage).
+- **Plan du potager** — dessin des carrés et placement des plantes, avec :
+  détection des **voisinages déconseillés**, **rotation des cultures** (plan par
+  année + alerte « même famille ici récemment »), **modèles tout faits**,
+  **suggestions de bonnes voisines**, **distances de plantation**, impression.
+- **Liste de courses du mois** — graines/plants à acheter ce mois-ci, avec
+  quantités (par nombre de personnes) et liens pour comparer les prix.
 - **Zone climatique** — tout le calendrier se décale selon la région
   (Nord / France tempérée / Sud).
+- **Mode sombre** — bascule clair/sombre, suit le système par défaut.
+- **Onboarding** — carte de premiers pas pour les débutants.
 - **Accès protégé** — mot de passe unique du foyer (session par cookie),
   protégé contre les tentatives répétées (anti-brute-force).
 - **Notifications** — rappels des tâches du mois envoyés sur **Discord**,
@@ -122,9 +129,9 @@ nano .env.production        # HOUSEHOLD_PASSWORD, CRON_SECRET, notifs…
 npm run build
 ```
 
-> Le dépôt est **privé** : pour `git clone`, utiliser un Personal Access Token
+> Si le dépôt est **privé**, le `git clone` nécessite un Personal Access Token
 > (`https://<TOKEN>@github.com/Flalal/potager.git`) ou une clé de déploiement
-> SSH ajoutée au dépôt.
+> SSH. S'il est **public**, le clone HTTPS fonctionne directement.
 
 > La base SQLite est créée automatiquement au premier lancement sous
 > `./data/potager.db`. Pour la placer sur un volume persistant, définir

docs/ARCHITECTURE.md

@@ -32,28 +32,33 @@ Navigateur ──HTTP──> Next.js (Node) ──> SQLite (node:sqlite)
 src/
   app/
     layout.tsx            Racine : thème, providers, nav, script anti-FOUC
-    page.tsx              Accueil « Ce mois-ci »
-    calendrier/           Calendrier annuel
+    page.tsx              Accueil « Ce mois-ci » (+ onboarding)
+    calendrier/           Calendrier annuel (imprimable)
     plantes/              Liste + fiches (génération statique)
-    potager/              Plan du potager
-    mon-jardin/           Plantations + météo + notifications
+    potager/              Plan du potager (rotation, modèles, distances)
+    mon-jardin/           Plantations + récolte prévue + tâches + météo
     journal/              Journal de jardin
+    courses/              Liste de courses du mois
     login/                Écran de connexion
     actions/auth.ts       Server Actions login / logout (+ anti-brute-force)
-    api/                  Route Handlers (garden, plots, journal, push, notify)
+    api/                  Route Handlers (garden, plots, journal, tasks, push, notify)
     manifest.ts           Manifest PWA
   components/             Composants UI (client pour l'interactif)
   lib/
     plants.ts             Catalogue statique (38 plantes)
     types.ts              Types + libellés
     calendar.ts           Logique calendaire (décalage zone, tâches, compat.)
+    garden-calc.ts        Récolte prévisionnelle (logique pure)
+    quantities.ts         Quantités conseillées par personne (logique pure)
+    shopping.ts           Liens d'achat / comparateur (logique pure)
+    plot-logic.ts         Rotation, suggestions, modèles de carrés (pure)
+    weather.ts            Arrosage + géocodage Open-Meteo (logique pure)
     climate.tsx           Contexte zone climatique (localStorage)
-    db.ts                 Connexion SQLite paresseuse + schéma
+    db.ts                 Connexion SQLite paresseuse + schéma + migrations
     session.ts            Sessions (cookie + DB)
     login-throttle.ts     Anti-brute-force (logique pure)
-    *-store.ts            Accès DB côté serveur (garden, plots, journal, push…)
-    garden.ts/plots.ts/journal.ts   Hooks client (cache optimiste + fetch)
-    weather.ts            Conseils d'arrosage (logique pure) + Open-Meteo
+    *-store.ts            Accès DB côté serveur (garden, plots, journal, tasks, push…)
+    garden.ts/plots.ts/journal.ts/tasks.ts   Hooks client (cache optimiste + fetch)
   proxy.ts                Garde des routes (ex-middleware)
 public/
   sw.js                   Service worker (push + cache hors-ligne)
@@ -78,14 +83,28 @@ Créé automatiquement au démarrage (`CREATE TABLE IF NOT EXISTS`, voir `db.ts`
 | --- | --- |
 | `sessions` | jetons de session (token, expiration) |
 | `plantations` | plantes installées (Mon jardin) |
-| `plots` | parcelles du plan (grille `cells` en JSON) |
+| `plots` | parcelles du plan ; `cells` (année courante) + `layouts` (JSON par année) + `year` |
 | `journal_entries` | journal (récolte/semis/observation…) |
+| `task_done` | tâches cochées (clé `uid:année-mois:libellé`) |
 | `push_subscriptions` | abonnements Web Push |
 | `login_attempts` | compteur anti-brute-force par IP |
 
 Connexion **paresseuse** (ouverte à la première requête, pas à l'import) pour
 éviter les verrous entre les workers du build ; `PRAGMA busy_timeout` + WAL.
 
+**Migrations** : `node:sqlite` n'a pas de système de versions ; `db.ts` applique
+des `ALTER TABLE` idempotents (try/catch) au démarrage — c'est ainsi que les
+colonnes `year`/`layouts` ont été ajoutées à `plots`.
+
+### Plan du potager & rotation
+
+Chaque carré stocke un **layout par année** (`layouts: { "2025": cells, … }`).
+Le sélecteur d'année change le layout édité. `plot-logic.ts` calcule :
+`rotationConflicts` (même famille au même endroit dans les 3 ans précédents),
+`suggestionsForPlot` (bonnes voisines compatibles) et `PLOT_TEMPLATES` (carrés
+tout faits, sans conflit). Les distances de plantation viennent du champ
+`espacement` des fiches.
+
 ## Flux de données (client ↔ serveur)
 
 Les hooks `useGarden` / `usePlots` / `useJournal` suivent le même patron :
@@ -127,10 +146,12 @@ partir des plantations.
 
 ## Météo
 
-`weather.ts` contient la **logique pure** (`wateringAdvice`, `summarize`) testée
-unitairement. Le composant `WeatherAdvice` géolocalise le navigateur et appelle
-**Open-Meteo** (gratuit, sans clé, CORS) côté client, puis affiche un conseil
-d'arrosage. La position est mémorisée en `localStorage`.
+`weather.ts` contient la **logique pure** (`wateringAdvice`, `summarize`,
+`geocodeUrl`, `firstGeocode`) testée unitairement. Le composant `WeatherAdvice`
+obtient la position par **géolocalisation** ou par **recherche de ville**
+(géocodage Open-Meteo), appelle **Open-Meteo** (gratuit, sans clé, CORS) côté
+client, puis affiche un conseil d'arrosage. La position est mémorisée en
+`localStorage`.
 
 ## PWA
 
@@ -149,11 +170,15 @@ applique le thème avant le premier paint (anti-FOUC) et `<html>` porte
 
 ## Tests
 
-**Vitest** (environnement `node`). Couvre la logique pure :
+**Vitest** (environnement `node`). Couvre la logique pure (48 tests) :
 
 - `calendar.test.ts` — décalage de zone, tâches du mois, compatibilités.
 - `login-throttle.test.ts` — verrou/fenêtre/réinitialisation.
-- `weather.test.ts` — conseils d'arrosage, agrégation Open-Meteo.
+- `weather.test.ts` — arrosage, agrégation et géocodage Open-Meteo.
+- `garden-calc.test.ts` — récolte prévisionnelle.
+- `quantities.test.ts` — quantités conseillées.
+- `shopping.test.ts` — liens d'achat.
+- `plot-logic.test.ts` — rotation, suggestions, validité des modèles.
 
 `npm test` (CI) / `npm run test:watch` (dev).
 

docs/GUIDE.md

@@ -40,30 +40,56 @@ Le mois en cours est surligné.
 ## Fiches plantes
 
 Chaque fiche détaille exposition, sol, arrosage, levée, espacement, ravageurs,
-rotation (famille), compagnonnage (bonnes/mauvaises associations) et un
-mini-calendrier. Bouton **Ajouter à mon jardin** pour suivre la plante.
+rotation (famille), compagnonnage, un mini-calendrier, la **quantité conseillée**
+(ex. ≈ 8 pieds pour 4 pers.) et des **liens d'achat** (« Comparer les prix »
+pour trouver le moins cher). Bouton **Ajouter à mon jardin** pour suivre la
+plante.
 
 ## Plan du potager
 
 Dessinez vos **carrés** (lignes × colonnes), puis placez vos plantes :
 
-1. créez un carré (nom, dimensions) ;
+1. créez un carré, **ou partez d'un modèle tout fait** (Carré du débutant,
+   Tomates & basilic, Carré d'aromates, Carré d'automne) ;
 2. dans la **palette**, choisissez une plante (ou la **gomme**) ;
 3. cliquez les cases pour les remplir.
 
-L'outil **signale en rouge ⚠️** deux voisines déconseillées (compagnonnage).
-Vous pouvez renommer, redimensionner ou supprimer un carré.
+L'outil vous aide :
+
+- **⚠️ Voisinage déconseillé** : deux voisines incompatibles sont entourées
+  de rouge.
+- **🔁 Rotation** : changez l'**année** du carré ; si vous replantez la même
+  famille au même endroit dans les 3 ans, la case passe en orange.
+- **💡 Bonnes voisines à ajouter** : suggestions compatibles avec ce qui est
+  déjà placé (cliquez pour les prendre comme pinceau).
+- **📏 Distances de plantation** : la liste des espacements à respecter pour
+  chaque plante du carré (aussi dans l'infobulle de chaque case).
+
+Bouton **🖨️ Imprimer le plan** pour l'emporter au jardin. Vous pouvez renommer,
+redimensionner ou supprimer un carré.
 
 ## Mon jardin
 
-La liste de vos plantations, avec pour chacune les **tâches du mois** (récolte,
-soins, arrosage). On y trouve aussi :
+La liste de vos plantations. Pour chacune :
+
+- **Récolte prévue** : estimée à partir de votre date de plantation et de votre
+  région.
+- **Tâches du mois** (récolte, soins, arrosage) : **cochez-les** (✅) quand
+  c'est fait — l'état est enregistré et se réinitialise chaque mois.
 
-- **Conseils d'arrosage météo** : cliquez « Activer la localisation » pour que
-  l'app récupère la météo locale (via Open-Meteo) et vous dise s'il faut
-  arroser ou non (pluie/chaleur prises en compte).
+On y trouve aussi :
+
+- **Conseils d'arrosage météo** : saisissez votre **ville** (ou « 📍 Ma
+  position ») pour que l'app récupère la météo locale (Open-Meteo) et vous dise
+  s'il faut arroser ou non (pluie/chaleur prises en compte).
 - **Notifications** : bouton « 🔔 Activer les rappels » (voir plus bas).
 
+## Liste de courses du mois
+
+La page **Courses** réunit tout ce qu'il faut acheter ce mois-ci (graines à
+semer, plants à repiquer), avec la **quantité conseillée** selon le nombre de
+personnes (réglable) et un lien **« Comparer les prix »** par plante.
+
 ## Journal de jardin
 
 Gardez la trace de votre saison : récoltes, semis, plantations, observations,