home_hub/docs/plan.md

HomeHub — Plan de développement

Approche itérative : chaque phase livre quelque chose d'utilisable.
Stack : FastAPI · React/Vite/TS · PostgreSQL 16 · Docker Compose

---

Phase 1 — Socle technique

Objectif : environnement opérationnel, rien de métier, mais tout tourne.

Backend

• Structure projet FastAPI (app/api/, app/core/, app/models/, app/schemas/, app/services/)
• Configuration SQLAlchemy 2.0 async + pool de connexions
• Création des schémas PostgreSQL (todos, shopping, notes) via Alembic
• Migration initiale : toutes les tables (voir spec section 3)
• Endpoint santé : GET /api/health
• Module media (app/services/media.py) :
  • Validation des formats acceptés (JPG, PNG, SVG, WebP, WebM, M4A)
  • Génération miniature Pillow : 150×150 (shopping), 300×300 (notes), 400×300 (inline)
  • Sauvegarde originals/ + thumbnails/ sur le volume
  • Endpoint POST /api/media/upload → retourne { file_path, thumbnail_path }
  • Endpoint DELETE /api/media/{uuid} → supprime original + miniature
• Middleware CORS pour réseau local 10.0.0.0/22
• Configuration via variables d'environnement (.env)
• Dockerfile backend (Python 3.12 slim)

Frontend

• Scaffold Vite + React 18 + TypeScript
• Tailwind CSS configuré avec les tokens Gruvbox (via tokens.json)
• Intégration design_system/components/ui-kit.jsx
• @vite-pwa/plugin configuré (Service Worker + manifest)
• manifest.json avec icônes iOS + Android
• Routage React Router v6
• Layout de base : navigation mobile (bottom bar) + navigation laptop (sidebar)
• Dockerfile frontend (Nginx)

Infra

• docker-compose.yml avec 3 services (frontend, backend, db)
• Volume PostgreSQL persistant
• Volume uploads persistant (/uploads/)
• docker-compose.dev.yml avec hot reload (volumes montés)
• Fichier .env.example
• Script dev.sh pour démarrage local rapide
• Script de seed (backend/app/data/seed.py) : charge seed_products.json (113 produits) + seed_stores.json (9 magasins) en base au premier démarrage

---

Phase 2 — Module Todos

Objectif : créer, lister, modifier, terminer et reporter des tâches depuis mobile et laptop.

Backend

• GET /api/todos — liste avec filtres (domaine, statut, priorité, tags)
• POST /api/todos — création
• PATCH /api/todos/{id} — mise à jour partielle
• DELETE /api/todos/{id} — suppression
• POST /api/todos/{id}/postpone — incrémente postponed_count + décale due_date
• Schémas Pydantic : TodoCreate, TodoUpdate, TodoResponse

Frontend Mobile

• Page Todos : liste des tâches en cours, groupées par domaine
• Bouton "+ Tâche" flottant → formulaire rapide (titre + domaine + date optionnelle)
• Swipe droite → marquer done
• Swipe gauche → actions (reporter 1j / reporter 1 semaine / supprimer)
• Badge compteur par domaine

Frontend Laptop

• Vue tableau avec filtres : domaine, statut, priorité, tags, période
• Formulaire complet (tous les champs)
• Tri multi-colonnes
• Sélection multiple + actions groupées

---

Phase 3 — Module Notes / Listes diverses

Objectif : saisie rapide de notes avec photo, audio et GPS depuis smartphone.

Backend

• GET /api/notes — liste avec search full-text + filtres tags/catégorie
• POST /api/notes — création
• PATCH /api/notes/{id} — mise à jour
• DELETE /api/notes/{id} — suppression
• POST /api/notes/{id}/attachments — upload fichier (image/audio)
• DELETE /api/notes/{id}/attachments/{att_id} — suppression pièce jointe
• Compression image Pillow → WebP (fallback serveur)
• Recherche FTS PostgreSQL français

Frontend Mobile

• Page Notes : liste chronologique avec aperçu
• Bouton "+ Note" → formulaire rapide (contenu + tags)
• Bouton 📷 → Camera API (capture directe ou import galerie)
• Bouton 🎤 → MediaRecorder (enregistrement audio avec waveform visuel)
• Bouton 📍 → Geolocation API → affichage coordonnées
• Compression WebP côté client (Canvas API) avant upload
• Visionneuse photo inline
• Lecteur audio inline
• Bouton 📄 → OCR sur photo → texte extrait inséré dans le contenu de la note

Frontend Laptop

• Grille notes avec vignettes photo
• Recherche full-text avec surlignage
• Filtres : catégorie, tags, avec photo, avec audio, avec GPS
• Formulaire étendu avec champs métadonnées libres (clé/valeur)
• Vue carte pour les notes avec GPS (Leaflet.js)

---

Phase 4 — Module Shopping (base)

Objectif : liste de courses fonctionnelle en magasin depuis smartphone.

Backend

• GET /api/shopping/products — catalogue avec recherche
• POST /api/shopping/products — ajout produit catalogue
• PATCH /api/shopping/products/{id} — modification produit
• GET /api/shopping/stores — liste magasins
• POST /api/shopping/stores — ajout magasin
• GET /api/shopping/lists — listes de courses
• POST /api/shopping/lists — création liste (avec génération auto depuis frequency_score)
• GET /api/shopping/lists/{id}/items — articles de la liste
• POST /api/shopping/lists/{id}/items — ajout article
• PATCH /api/shopping/list_items/{id} — cocher / modifier prix relevé
• POST /api/shopping/lists/{id}/finish — terminer les courses (report automatique articles non cochés → nouvelle liste)
• Logique de report : créer liste semaine+1 avec carried_over = true sur articles non cochés

Frontend Mobile — Création liste

• Page accueil shopping : liste des semaines
• "Nouvelle liste" → picker semaine + suggestions top produits (frequency_score)
• Recherche produit dans catalogue + ajout 1 tap
• Ajout rapide produit hors catalogue → création à la volée dans catalogue

Frontend Mobile — Mode courses

• Vue liste triée par catégorie/rayon
• Wake Lock API activée automatiquement à l'ouverture
• Grand bouton checkbox par article (48px+)
• Tap sur prix → champ numérique rapide
• Swipe gauche → retirer de la liste
• Bouton "Terminer les courses" avec confirmation

Frontend Laptop — Gestion catalogue

• Tableau produits avec photo, marque, catégorie, frequency_score
• CRUD complet produits
• Gestion magasins
• Import/export catalogue CSV

---

Phase 4b — Module scan + enrichissement catalogue produits

Objectif : scan code-barres depuis mobile, auto-remplissage depuis OpenFoodFacts, recherche image via SearXNG sur laptop.

Services Docker

• Dockerfile product-search/ : Python slim + requests + client OpenFoodFacts
• GET /lookup?barcode={code} → OpenFoodFacts barcode API
• GET /search?q={nom} → OpenFoodFacts text search
• GET /image-search?q={nom} → délègue à SearXNG (images uniquement)
• Ajout service product-search dans docker-compose.yml (port 8002)
• Ajout service searxng dans docker-compose.yml (image officielle, port 8080 interne)
• Configuration SearXNG : désactiver toutes les catégories sauf images

Backend (endpoints proxy)

• GET /api/products/lookup?barcode= → proxifie vers product-search
• GET /api/products/search?q= → proxifie vers product-search
• GET /api/products/image-search?q= → proxifie vers product-search (laptop uniquement)
• POST /api/products/import → crée un produit dans le catalogue depuis les données OpenFoodFacts retournées

Frontend Mobile — scan

• Intégration zxing-js (BarcodeReader via flux caméra)
• Bouton "Scanner" dans le formulaire d'ajout de produit
• Sur scan réussi → appel /api/products/lookup → auto-remplissage formulaire
• Si barcode inconnu → formulaire vide (saisie manuelle)

Frontend Laptop — enrichissement catalogue

• Champ de recherche texte → /api/products/search → liste de résultats OpenFoodFacts
• Bouton "Chercher une image" → /api/products/image-search → grille de miniatures SearXNG
• Clic sur une image → téléchargement + génération miniature via module media

---

Phase 5 — Service OCR (conteneur dédié, partagé)

Objectif : service OCR partagé, prérequis pour le shopping avancé et les notes avancées.

• Dockerfile ocr/ : image Python slim + Tesseract 5 + langues (fra, eng) + Pillow
• POST /extract : reçoit une image (multipart), retourne { text, confidence }
• Pré-processing Pillow : redimensionnement, niveaux de gris, amélioration contraste
• Endpoint backend unifié POST /api/ocr/extract : proxifie vers ocr:8001
• Gestion du service inactif : retour d'erreur propre sans bloquer le module appelant
• Ajout du service ocr dans docker-compose.yml

---

Phase 6 — Module Shopping avancé (OCR + suivi prix)

Objectif : OCR étiquettes et tickets, graphiques d'évolution des prix.

Backend

• POST /api/shopping/ocr/price-tag — photo étiquette → extraction prix via service OCR
• POST /api/shopping/ocr/receipt — photo ticket → reconciliation avec liste
• GET /api/shopping/products/{id}/price-history — historique prix par produit + magasin

Frontend Mobile

• Bouton 📷 sur chaque article → OCR étiquette → pré-remplissage prix
• Bouton "Scanner ticket" en fin de courses → OCR receipt → confirmation reconciliation

Frontend Laptop

• Graphique courbe d'évolution du prix par produit (Recharts ou Chart.js)
• Comparaison prix par magasin
• Export CSV historique des prix

---

Phase 7 — MCP Server

Objectif : exposer les outils HomeHub aux agents IA (Hermes, Claude, etc.).

• Intégration SDK MCP Python (mcp package)
• Endpoint SSE /mcp
• Implémentation des 6 outils (voir spec section 2.4)
• Tests avec Claude Code (MCP client)
• Documentation OpenAPI des outils MCP

---

Phases futures (hors scope initial)

---

Phases futures (hors scope initial)

Phase 8 — Authentification multi-utilisateurs

• Auth JWT (login / refresh token)
• Activation de owner_id dans toutes les tables
• Middleware d'authentification FastAPI
• Page connexion React

Phase 9 — Calendrier + intégrations

• Sync Google Calendar (OAuth2 + worker)
• Endpoint CalDAV pour iOS
• Redis pour la queue de synchronisation
• Webhooks Gitea → Kanban
• Home Assistant : capteur "tâches en retard"

Phase 10 — Vision IA

• Endpoint analyse frigo (photo → suggestions liste de courses)
• Amélioration OCR via modèle Vision local (Ollama)

---

Ordre de développement recommandé

Phase 1 → Phase 2 → Phase 4 (shopping base) → Phase 4b (scan + OpenFoodFacts) → Phase 3 (notes) → Phase 5 (OCR) → Phase 6 (shopping avancé) → Phase 7 (MCP)

Rationale : les todos sont les plus simples (validation du socle), le shopping mobile de base est prioritaire pour usage réel, les notes viennent ensuite, le service OCR est posé avant d'en avoir besoin, puis les features avancées.