# HomeHub — Spécification Fonctionnelle

> Version 0.1 — mai 2026  
> Application d'organisation personnelle auto-hébergée (PWA)  
> Stack : FastAPI · React/Vite/TypeScript · PostgreSQL 16 · Docker Compose

---

## 1. Contexte et objectifs

HomeHub est une PWA auto-hébergée sur Proxmox 9, conçue pour un usage intensif mobile (smartphone en magasin, sur le terrain) et une consultation plus complète sur laptop. L'application est **mono-utilisateur** au démarrage, avec une architecture prévue pour évoluer vers le multi-utilisateur sans refactoring majeur (colonne `owner_id` nullable dans toutes les tables).

---

## 2. Architecture technique

### 2.1 Services Docker Compose (6 services)

| Service | Image | Port interne | Rôle |
|---------|-------|-------------|------|
| `frontend` | Nginx léger | 3000 | Sert le build React/Vite (PWA statique) |
| `backend` | Python 3.12 / FastAPI | 8000 | API REST + MCP server |
| `db` | PostgreSQL 16 | 5432 | Base de données multi-schémas |
| `ocr` | Tesseract + Pillow | 8001 | Service OCR partagé (toutes les photos de l'app) |
| `product-search` | Python slim | 8002 | Lookup OpenFoodFacts + fallback SearXNG |
| `searxng` | SearXNG officiel | 8080 | Métamoteur de recherche — fallback image produits |

**Services isolés et arrêtables indépendamment :**
- `ocr` (4) — arrêtable sans impact sur la liste de courses. Seule la saisie OCR de prix devient indisponible
- `product-search` (5) — arrêtable sans impact. Seule la recherche OpenFoodFacts devient indisponible
- `searxng` (6) — arrêtable sans impact. Seul le fallback image produit devient indisponible

Les services 1/2/3 (`frontend`, `backend`, `db`) sont les seuls **obligatoires** pour le fonctionnement de base. Un `docker compose stop ocr product-search searxng` laisse l'app 100% fonctionnelle pour la liste de courses.

**Nginx Proxy Manager** (déjà en place sur le homelab) gère l'entrée HTTPS et le routage vers ces services.

### 2.2 Évolutions prévues (non bloquantes)

- Redis → ajouté avec la sync Google Calendar (Phase 6)
- Auth JWT → activation de `owner_id` + écran de connexion (Phase 7)
- Agent Hermes (Vision LLM) → analyse photo frigo
- Webhooks Gitea → intégration Kanban
- Home Assistant → capteurs tâches en retard

### 2.3 Stockage fichiers et module media

Volume Docker `/uploads/` servi par le backend. Toutes les images passent par le module `media` du backend à la réception.

**Pipeline de traitement à l'upload :**
1. Compression côté client (Canvas API → WebP) avant envoi — réduit la bande passante
2. Validation format serveur (JPG, PNG, SVG, WebP acceptés)
3. Génération automatique d'une miniature (Pillow) — stockée séparément
4. Les deux fichiers sont enregistrés sur le volume

**Structure du volume :**
```
/uploads/
  images/
    originals/{uuid}.webp       ← image compressée (pleine résolution utile)
    thumbnails/{uuid}_thumb.webp ← miniature générée par Pillow
  audio/
    {uuid}.webm                 ← enregistrements audio
```

**Tailles de miniatures par contexte :**

| Contexte | Taille thumbnail |
|----------|-----------------|
| Produit catalogue shopping | 150 × 150 px (carré, centré) |
| Note (vignette liste) | 300 × 300 px (carré, centré) |
| Pièce jointe (aperçu inline) | 400 × 300 px (paysage, centré) |

Les miniatures sont toujours servies pour les vues liste/grille. L'original n'est chargé qu'à la demande (plein écran, zoom). Formats audio acceptés : WebM, M4A.

### 2.4 MCP Server

Intégré dans FastAPI sur `/mcp` (protocole SSE). Expose les outils suivants aux agents IA (Hermes, Claude, etc.) :

| Outil | Description |
|-------|-------------|
| `get_todos()` | Retourne les tâches urgentes / en cours |
| `add_todo(title, due_date)` | Crée une tâche |
| `get_shopping_list()` | Retourne la liste de courses active |
| `add_shopping_item(name, category)` | Ajoute un article à la liste active |
| `search_notes(query)` | Recherche full-text dans les notes |
| `add_note(title, content, tags)` | Crée une note |

---

## 3. Schéma de base de données

### 3.1 Schema `shopping`

#### `shopping.products` — Catalogue global
| Colonne | Type | Description |
|---------|------|-------------|
| id | UUID PK | |
| name | VARCHAR(150) | Nom produit |
| brand | VARCHAR(100) | Marque |
| category | VARCHAR(50) | Rayon magasin (tri in-store) |
| image_path | VARCHAR(255) | Chemin original `/uploads/images/originals/` |
| thumbnail_path | VARCHAR(255) | Chemin miniature `/uploads/images/thumbnails/` |
| default_unit | VARCHAR(20) | kg / L / unité |
| barcode | VARCHAR(50) | Code-barres (scan futur) |
| frequency_score | INT DEFAULT 0 | Score d'habitude (suggestions auto) |
| owner_id | UUID NULL | Prévu multi-user |
| created_at | TIMESTAMPTZ | |

**Catégories produits (tri rayon en magasin) :**
`Fruits` · `Légumes` · `Viandes` · `Charcuterie` · `Poissons` · `Produits laitiers` · `Boulangerie` · `Épicerie salée` · `Épicerie sucrée` · `Condiments` · `Boissons` · `Entretien` · `Pharmacie` · `Animaux` · `Carburant` · `Électronique` · `Divers`

**Magasins pré-configurés (seed) :** Lidl · Intermarché · Super U · Gamm Vert · Weldom · Cosi · Bricocash · Tinel · Marie Blachère

**Données de démarrage :** 113 produits dans `backend/app/data/seed_products.json`, 9 magasins dans `seed_stores.json` — chargés automatiquement au premier démarrage.

#### `shopping.stores` — Magasins
| Colonne | Type | Description |
|---------|------|-------------|
| id | UUID PK | |
| name | VARCHAR(100) | Ex: Lidl, Carrefour |
| location | TEXT | Adresse ou coordonnées GPS |
| owner_id | UUID NULL | |

#### `shopping.price_history` — Historique des prix
| Colonne | Type | Description |
|---------|------|-------------|
| id | UUID PK | |
| product_id | UUID → products | |
| store_id | UUID → stores NULL | |
| price | NUMERIC(8,2) | Prix relevé |
| unit | VARCHAR(20) | kg / L / unité |
| quantity | NUMERIC(8,3) | Quantité associée |
| source | VARCHAR(20) | `manual` / `ocr_tag` / `ocr_receipt` |
| recorded_at | TIMESTAMPTZ | |

#### `shopping.lists` — Listes de courses
| Colonne | Type | Description |
|---------|------|-------------|
| id | UUID PK | |
| name | VARCHAR(100) | Ex: "Semaine du 26 mai" |
| store_id | UUID NULL | Magasin cible |
| week_date | DATE | Date de la semaine cible |
| status | VARCHAR(20) | `draft` / `active` / `done` |
| owner_id | UUID NULL | |
| created_at | TIMESTAMPTZ | |

#### `shopping.list_items` — Articles dans une liste
| Colonne | Type | Description |
|---------|------|-------------|
| id | UUID PK | |
| list_id | UUID → lists | |
| product_id | UUID → products NULL | Lié au catalogue (optionnel) |
| custom_name | VARCHAR(150) | Si article hors catalogue |
| quantity | NUMERIC(8,3) | |
| unit | VARCHAR(20) | |
| is_checked | BOOLEAN DEFAULT FALSE | Coché en magasin |
| price_recorded | NUMERIC(8,2) | Prix relevé pendant les courses |
| carried_over | BOOLEAN DEFAULT FALSE | Reporté depuis la semaine précédente |
| sort_order | INT | Tri par rayon/catégorie |

### 3.2 Schema `todos`

#### `todos.items`
| Colonne | Type | Description |
|---------|------|-------------|
| id | UUID PK | |
| title | VARCHAR(255) | |
| body | TEXT | Texte libre |
| url | TEXT | Lien optionnel |
| domain | VARCHAR(50) | Voir liste des domaines |
| category | VARCHAR(50) | Sous-catégorie libre |
| tags | VARCHAR(50)[] | Array · index GIN |
| status | VARCHAR(20) | `pending` / `done` / `cancelled` |
| priority | VARCHAR(10) | `low` / `medium` / `high` |
| due_date | TIMESTAMPTZ | Date objectif |
| postponed_count | INT DEFAULT 0 | Nombre de reports |
| created_at | TIMESTAMPTZ DEFAULT NOW() | Auto |
| updated_at | TIMESTAMPTZ | |
| owner_id | UUID NULL | |

**Domaines disponibles** : `informatique` · `diy` · `electronique` · `domotique` · `bricolage` · `jardin` · `cuisine` · `voyage` · `animaux`

### 3.3 Schema `notes`

#### `notes.items`
| Colonne | Type | Description |
|---------|------|-------------|
| id | UUID PK | |
| title | VARCHAR(255) | Optionnel |
| content | TEXT NOT NULL | Texte de la note |
| category | VARCHAR(50) | |
| tags | VARCHAR(50)[] | Index GIN |
| gps_lat | NUMERIC(10,7) | Latitude GPS |
| gps_lon | NUMERIC(10,7) | Longitude GPS |
| metadata | JSONB | Paires clé/valeur libres (référence, magasin…) |
| created_at | TIMESTAMPTZ DEFAULT NOW() | |
| owner_id | UUID NULL | |

Index : `GIN(tags)` + `GIN(to_tsvector('french', title || ' ' || content))` (recherche full-text)

#### `notes.attachments`
| Colonne | Type | Description |
|---------|------|-------------|
| id | UUID PK | |
| note_id | UUID → items | |
| file_path | VARCHAR(255) | Chemin original `/uploads/images/originals/` |
| thumbnail_path | VARCHAR(255) | Chemin miniature (NULL si audio) |
| file_type | VARCHAR(20) | `image` / `audio` |
| original_name | VARCHAR(255) | |
| created_at | TIMESTAMPTZ | |

---

## 4. Modules fonctionnels

### 4.1 Module Shopping — Liste de courses

#### Principe fondamental — ne jamais bloquer

> **L'objectif principal est simple : créer une liste en début de semaine, cocher les articles pendant les courses.**
> Toutes les autres fonctionnalités (prix, OCR, stats, suggestions automatiques) sont **optionnelles** et n'apparaissent jamais dans le chemin principal. Un utilisateur qui ignore tout ça doit pouvoir utiliser l'app sans friction.

#### Concept général
La liste de courses est générée **à partir du catalogue global** de produits. Le `frequency_score` de chaque produit augmente à chaque achat — ce score alimente les suggestions automatiques de la semaine. L'utilisateur valide/modifie/complète la liste avant de partir en courses.

Les articles **non cochés** à la fin des courses sont automatiquement reportés (`carried_over = true`) dans la liste de la semaine suivante.

La saisie de prix est **toujours optionnelle** — le champ prix est discret, accessible d'un tap long ou d'un bouton secondaire, jamais dans le chemin de cocher un article.

#### Interface mobile (priorité)
- **Création de liste** : interface ultra-simple — picker de la semaine, suggestion automatique des produits habituels (top frequency_score), ajout rapide d'un produit (recherche dans le catalogue ou création à la volée)
- **Mode courses** (liste active) :
  - Grands boutons tactiles (min 48px)
  - Articles triés par rayon/catégorie
  - Tap pour cocher un article
  - Swipe gauche → supprimer de la liste
  - Champ prix rapide au tap (clavier numérique)
  - **Wake Lock API** : l'écran ne se verrouille pas pendant les courses
  - Bouton "Terminer les courses" → génère la liste suivante avec les articles non cochés

#### Interface laptop (complète)
- Vue tableau avec filtre par magasin, catégorie, statut
- Gestion du catalogue global de produits (CRUD complet)
- Gestion des magasins
- Graphiques d'évolution des prix par produit
- Export CSV de l'historique des prix

#### Module OCR (service Docker isolé, partagé entre tous les modules)

Le service OCR tourne dans son propre conteneur Docker (`ocr:8001`). Il est utilisable par tous les modules de l'application via l'endpoint unifié `POST /api/ocr/extract` du backend.

| Module | Usage OCR |
|--------|-----------|
| Shopping | Lecture étiquette prix en rayon → pré-remplissage prix |
| Shopping | Lecture ticket de caisse → réconciliation finale liste |
| Notes | Extraction texte depuis une photo (photo de document, panneau, référence) |
| Futur | Tout import photo dans l'application |

Le module OCR est **toujours optionnel** : si le service est arrêté, les autres fonctionnalités de l'app ne sont pas impactées. Backend : Tesseract (local). Fallback possible : Ollama Vision (Hermes) en remplaçant simplement le service `ocr` dans le Docker Compose.

#### Suivi des prix
Chaque prix saisi (manuel, OCR étiquette ou OCR ticket) alimente `price_history`. Sur laptop, un graphique en courbe par produit montre l'évolution du prix dans le temps, par magasin.

### 4.2 Module Notes / Listes diverses

Saisie rapide de notes avec support multimédia et géolocalisation.

**Champs** :
- Titre (optionnel)
- Contenu texte libre (saisie rapide)
- Date (auto à la création, modifiable)
- Catégorie
- Tags (multi-valeurs, autocomplétion)
- Photo(s) : capture directe via Camera API ou import depuis galerie. Compression WebP avant upload
- Audio : enregistrement via MediaRecorder API. Format WebM/M4A
- GPS : bouton "Localiser" → Geolocation API → stocke lat/lon, affiche adresse via reverse geocoding (optionnel)
- Métadonnées libres : paires clé/valeur (ex: "Référence: X12-34", "Magasin: Brico Dépôt")

**Recherche** : full-text PostgreSQL en français sur titre + contenu + métadonnées. Filtres par catégorie, tags, présence de photo/audio/GPS.

### 4.3 Module Todos

Gestion de tâches classées par domaine.

**Champs** :
- Titre
- Texte libre (description)
- URL (lien externe optionnel)
- Domaine (liste fermée : voir section 3.2)
- Catégorie (libre)
- Tags (multi-valeurs)
- Statut : `pending` / `done` / `cancelled`
- Priorité : `low` / `medium` / `high`
- Date de création (auto)
- Date objectif (due_date)
- Compteur de reports (`postponed_count`)

**Interface mobile** : ajout rapide en 1 clic, vue liste épurée, actions swipe (reporter / terminer). Boutons "Reporter d'1 jour", "Reporter à la semaine prochaine".

**Interface laptop** : vue complète avec filtres multi-critères (domaine, statut, priorité, tags), tri, recherche textuelle.

---

## 5. Module scan code-barres / QR code

### Fonctionnement
- Librairie JS `zxing-js` (open-source, cross-platform) intégrée dans le frontend
- Accès via le flux Camera API (pas de capture photo — lecture en temps réel)
- Fonctionne sur iOS Safari et Android Chrome
- Déclenché par un bouton 📷 "Scanner" dans le formulaire d'ajout de produit

### Flux de résolution produit
```
Scan code-barres (EAN-13 / QR)
  → service product-search : GET /lookup?barcode={code}
    → 1. OpenFoodFacts API (base ~3M produits alimentaires)
       → trouvé : nom, marque, catégorie, image → auto-remplit le formulaire
    → 2. Si pas trouvé : retourne vide → saisie manuelle
       → enrichissement optionnel via recherche texte + SearXNG (laptop uniquement)
```

### Service `product-search` (Docker)
API Python légère qui centralise :
- `GET /lookup?barcode={code}` → OpenFoodFacts par code-barres
- `GET /search?q={nom}` → OpenFoodFacts par nom de produit
- `GET /image-search?q={nom}` → SearXNG image search (fallback, laptop uniquement)

Le backend FastAPI expose ces fonctionnalités via `/api/products/lookup`, `/api/products/search`, `/api/products/image-search`.

### Service `searxng` (Docker)
Instance SearXNG auto-hébergée, utilisée exclusivement pour la recherche d'images de produits non trouvés dans OpenFoodFacts. Accessible uniquement depuis l'interface laptop lors de l'enrichissement du catalogue. Non exposé publiquement via NPM.

---

## 6. Capacités natives smartphone (PWA)

| API navigateur | Usage |
|---------------|-------|
| Camera API | Capture photo directe (notes, OCR, produits) |
| MediaRecorder API | Enregistrement audio (notes vocales) |
| Geolocation API | Localisation GPS sur les notes |
| Wake Lock API | Écran actif pendant les courses |
| Web Share API | Partage de notes/listes vers autres apps |
| Liens `webcal://` | Abonnement calendrier natif iOS/Android (futur) |

---

## 7. Design system

Le design system **Gruvbox seventies** est intégré dès le départ.

- Fichiers : `design_system/tokens/tokens.css` · `design_system/components/ui-kit.jsx`
- Thème : dark par défaut, light disponible via `data-theme`
- Palette : orange brûlé `#fe8019` (accent), fond brun `#2a231d`, texte `#f2e5c7`
- 14 composants React disponibles (Button, IconButton, Toggle, StatusLed, BatteryGauge, RadialGauge, Popup, TreeNav, Sparkline, LineChart, Icon…)
- Fonts : Inter (UI) · JetBrains Mono (données) · Share Tech Mono (terminal/logs)
- Règles absolues : jamais de hex en dur, toujours `var(--token)`, `data-theme` obligatoire sur un parent

---

## 8. Interface utilisateur — principes

### Mobile-first
- Touch target minimum : 48px
- Composants d'action accessibles en 1 main
- Swipe sur les listes (reporter, terminer, supprimer)
- Chargement hors-ligne via Service Worker (cache assets + données critiques)
- Feedback haptique si disponible

### Distinction mobile / laptop
Certains modules ont deux pages dédiées selon la taille d'écran :

| Module | Mobile | Laptop |
|--------|--------|--------|
| Shopping | Création liste simple + mode courses | Catalogue produits + gestion magasins + graphiques prix |
| Todos | Ajout rapide + liste swipeable | Tableau filtrable multi-critères |
| Notes | Saisie rapide + media capture | Liste complète + recherche avancée |

---

## 9. Hors scope initial (Phase 1-5)

- Authentification multi-utilisateurs (Phase 7)
- Google Calendar / CalDAV (Phase 6)
- Kanban / Gitea webhooks (Phase 8)
- Home Assistant (Phase 8)
- Analyse frigo par Vision LLM / Hermes (Phase 9)
- Scan code-barres produits