🥚 Protéines - Suivi Nutritionnel Journalier

Application PWA de suivi des apports en protéines pour seniors

---

📋 Table des Matières

• Vue d'ensemble
• Fonctionnalités
• Technologies
• Prérequis
• Installation
• Utilisation
• Architecture
• Workflow de Développement
• Documentation
• Roadmap
• Contribution
• Licence

---

🎯 Vue d'ensemble

Protéines est une Progressive Web App (PWA) permettant à Denis (73 ans) et Marie Jo (71 ans) de suivre leurs apports quotidiens en protéines, repas par repas.

Objectif

Aider les seniors à atteindre leurs objectifs nutritionnels en protéines pour maintenir leur masse musculaire et leur santé.

Problème Résolu

• ✅ Calcul automatique des protéines
• ✅ Historique journalier illimité
• ✅ Base de données de 275 aliments
• ✅ Recommandations personnalisées par repas
• ✅ Synchronisation cloud (MongoDB)
• ✅ Fonctionnement offline (PWA)

Caractéristiques Principales

• 🚀 Léger : 120 KB total (31 KB compressé)
• ⚡ Rapide : LCP < 1.2s (WiFi)
• 📱 Mobile-first : Design responsive pastel
• 🔌 Offline : Service Worker + cache
• ☁️ Cloud : Synchronisation MongoDB
• 🎨 UX optimisée : CLS < 0.05

---

✨ Fonctionnalités

🥗 Gestion des Repas

5 repas par jour :

• Petit-déjeuner
• En-cas matin
• Déjeuner
• Goûter
• Dîner

Actions :

• ➕ Ajouter des aliments
• ✏️ Modifier les quantités
• 🗑️ Supprimer des items
• 📋 Copier vers l'autre utilisateur

🔍 Recherche d'Aliments (4 sources)

Ordre de priorité :

1. Mes aliments (aliments personnalisés) 🟣
2. Favoris (auto-learning) 🟡
3. Base locale (275 aliments) 🔵
4. Open Food Facts (API externe) ⚪

👥 Multi-utilisateur

• 2 profils : Denis / Marie Jo
• Configuration individuelle (âge, poids, objectif)
• Données séparées par personne
• Switch instantané

📊 Suivi et Statistiques

• Barre de progression visuelle
• Total quotidien vs objectif
• Recommandations par repas
• Historique illimité (navigation temporelle)

🎨 Aliments Personnalisés (v2.9.0)

• Créer ses propres aliments
• Nom + Protéines/100g + Portion
• Priorité absolue dans la recherche
• Gestion complète (ajout/suppression)

📱 PWA (Progressive Web App)

• Installation sur écran d'accueil
• Icône personnalisée
• Mode standalone
• Notifications (futures)
• Auto-update

---

🛠️ Technologies

Frontend

Technologie	Version	Usage
HTML5	-	Structure sémantique
CSS3	-	Design pastel, mobile-first
JavaScript	ES6+	Vanilla JS (pas de framework)
Service Worker	-	Cache, offline
PWA	-	Manifest, installation

Pas de framework : React/Vue/Angular volontairement évités pour :

• ⚡ Performance maximale
• 🪶 Taille minimale
• 🎯 Simplicité

Backend

Technologie	Version	Usage
PHP	8.4	API REST
MongoDB	7.x	Base NoSQL
Nginx	Latest	Serveur web
Composer	2.x	Dépendances PHP

Services Externes

• Open Food Facts : Base de données alimentaire collaborative
• GitHub : Versionning (git@github.com:Denis1953/proteines.git)

---

📦 Prérequis

Développement Local

# Serveur web
nginx >= 1.18

# PHP
php >= 8.0
php-fpm >= 8.0
php-mongodb

# Base de données
mongodb >= 4.4

# Outils
composer >= 2.0
git >= 2.25

Navigateurs Supportés

• ✅ Chrome/Edge 90+
• ✅ Safari 14+
• ✅ Firefox 88+
• ✅ Samsung Internet 14+

---

🚀 Installation

1. Cloner le Repository

cd /var/www
git clone git@github.com:Denis1953/proteines.git proteines-staging
cd proteines-staging

2. Installer les Dépendances PHP

composer install

3. Configurer MongoDB

# Démarrer MongoDB
sudo systemctl start mongodb

# Créer la base de données
mongosh
> use proteines
> db.createCollection("data")
> exit

4. Configurer Nginx

# Copier la configuration
sudo cp /etc/nginx/sites-available/proteines /etc/nginx/sites-available/proteines-staging

# Modifier le port et le root
sudo nano /etc/nginx/sites-available/proteines-staging
# listen 8083;
# root /var/www/proteines-staging;

# Activer le site
sudo ln -s /etc/nginx/sites-available/proteines-staging /etc/nginx/sites-enabled/

# Tester et recharger
sudo nginx -t
sudo systemctl reload nginx

5. Permissions

sudo chown -R www-data:www-data /var/www/proteines-staging
sudo chmod -R 755 /var/www/proteines-staging

6. Accéder à l'Application

Staging : http://51.77.151.209:8083 Production : http://51.77.151.209:8082

---

💡 Utilisation

Première Utilisation

1. Ouvrir l'application dans votre navigateur
2. Installer la PWA (optionnel)
   • Chrome : Menu > Installer l'application
   • Safari iOS : Partager > Sur l'écran d'accueil
3. Sélectionner votre profil (Denis ou Marie Jo)
4. Ajouter un repas : Cliquer sur "+" dans une carte repas
5. Rechercher un aliment : Taper dans la barre de recherche
6. Valider : L'application synchronise automatiquement

Fonctionnalités Avancées

Créer un aliment personnalisé :

1. Cliquer sur l'icône ⚙️ (Paramètres)
2. Onglet "Mes aliments"
3. Remplir : Nom, Protéines/100g, Portion
4. Cliquer "Ajouter"

Copier un repas :

1. Cliquer sur l'icône 📋 sur une carte repas
2. Cliquer à nouveau pour confirmer
3. Le repas est copié vers l'autre utilisateur

Navigation temporelle :

1. Utiliser les flèches ← → en haut
2. Consulter l'historique illimité
3. Impossible d'aller au-delà d'aujourd'hui

---

🏗️ Architecture

Structure du Projet

proteines/
├── api/
│   └── sync.php              # API REST synchronisation
├── css/
│   └── style.css             # Styles (19 KB)
├── data/
│   └── aliments.json         # Base locale 275 aliments
├── img/
│   ├── icon-192.png          # Icône PWA
│   └── icon-512.png          # Icône PWA
├── js/
│   └── app.js                # Logique métier (46 KB)
├── vendor/                   # Dépendances Composer
├── index.html                # Interface principale (21 KB)
├── manifest.json             # Manifeste PWA
├── sw.js                     # Service Worker
├── composer.json             # Dépendances PHP
├── .gitignore                # Exclusions Git
│
├── ARCHITECTURE.md           # Documentation architecture
├── SECURITY-AUDIT.md         # Audit de sécurité
├── PERFORMANCE-AUDIT.md      # Audit de performance
├── CHANGELOG.md              # Historique versions
├── WORKFLOW.md               # Workflow déploiement
├── README.md                 # Ce fichier
└── deploy.sh                 # Script de déploiement

Flux de Données

┌─────────────┐
│   Browser   │
└──────┬──────┘
       │
       ├─► index.html (PWA)
       │
       ├─► Service Worker (cache)
       │
       ├─► app.js (state management)
       │   │
       │   ├─► LocalStorage (backup local)
       │   │
       │   └─► /api/sync.php (cloud)
       │       │
       │       └─► MongoDB (persistance)
       │
       └─► Open Food Facts API (recherche)

Décisions Architecturales (ADR)

ADR-001 : Vanilla JavaScript

• ✅ Performance maximale
• ✅ Taille minimale (pas de framework)
• ❌ Code plus verbeux

ADR-002 : MongoDB (NoSQL)

• ✅ Schema flexible
• ✅ Facile à faire évoluer
• ❌ Pas de relations complexes

ADR-003 : Double backup (localStorage + MongoDB)

• ✅ Résilience maximale
• ✅ Offline-first
• ❌ Redondance

ADR-004 : Network First (Service Worker)

• ✅ Données toujours fraîches
• ❌ Nécessite connexion

ADR-005 : CSS Containment

• ✅ CLS excellent (< 0.05)
• ❌ Code CSS complexe

➡️ Voir ARCHITECTURE.md pour détails complets

---

🔄 Workflow de Développement

Méthodologie BMAD

Build → Measure → Analyze → Decide

Application systématique du cycle BMAD pour toute modification :

1. BUILD    → Développer sur STAGING
2. MEASURE  → Collecter logs/métriques
3. ANALYZE  → Examiner performances/bugs
4. DECIDE   → Déployer en PRODUCTION (validation explicite)

Environnements

Environnement	URL	Branche	Port
Staging	http://51.77.151.209:8083	develop	8083
Production	http://51.77.151.209:8082	main	8082

Processus de Développement

1. Développer sur Staging

cd /var/www/proteines-staging
git checkout develop

# Faire vos modifications...

# Tester localement
curl http://51.77.151.209:8083

2. Committer

git add .
git commit -m "v2.9.1 - Description courte

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
git push origin develop

3. Déployer en Production

# Utiliser le script automatique
cd /var/www/proteines
./deploy.sh

# Ou manuellement
git checkout main
git merge develop
git push origin main

Versioning

Format : vMAJOR.MINOR.PATCH

• MAJOR : Changements incompatibles (v3.0.0)
• MINOR : Nouvelles fonctionnalités (v2.10.0)
• PATCH : Corrections de bugs (v2.9.1)

Exemples :

✅ v2.9.1 - Fix bug recherche favoris
✅ v2.10.0 - Ajout export CSV
✅ v3.0.0 - Multi-familles avec authentification

➡️ Voir WORKFLOW.md pour détails complets

---

📚 Documentation

Documents Disponibles

Document	Description	Lignes
README.md	Vue d'ensemble (ce fichier)	600+
ARCHITECTURE.md	Architecture détaillée	400+
SECURITY-AUDIT.md	Audit de sécurité complet	600+
PERFORMANCE-AUDIT.md	Audit de performance PWA	800+
CHANGELOG.md	Historique des versions	500+
WORKFLOW.md	Workflow déploiement	100+

Liens Utiles

• Repository : git@github.com:Denis1953/proteines.git
• Issues : GitHub Issues
• Documentation API : ARCHITECTURE.md

---

🗺️ Roadmap

✅ Version 2.9.0 (Actuelle)

• Aliments personnalisés
• Base locale 275 aliments
• Système de favoris
• Navigation temporelle
• PWA complète
• Synchronisation MongoDB

🔜 Version 2.10.0 (Q1 2026)

Focus : Sécurité & Performance

• HTTPS obligatoire
• Correction vulnérabilités XSS
• Headers de sécurité (CSP)
• Minification JS/CSS
• Compression Brotli
• Export CSV
• Statistiques hebdomadaires

🔮 Version 2.11.0 (Q2 2026)

Focus : Analyse & Insights

• Graphiques de tendances
• Statistiques mensuelles
• Notifications push
• Mode sombre
• Objectifs par repas personnalisables

🚀 Version 3.0.0 (Q3 2026)

Focus : Multi-utilisateurs & Cloud (Breaking Changes)

• Authentification multi-familles
• Comptes utilisateurs sécurisés
• Synchronisation temps réel
• API RESTful complète
• Tableau de bord admin

➡️ Voir CHANGELOG.md pour détails

---

🐛 Problèmes Connus

Sécurité (Score 4.5/10)

⚠️ CRITIQUES :

• Pas d'authentification (family_id hardcodé)
• Pas de HTTPS
• CORS ouvert à tous
• 19 vulnérabilités XSS (innerHTML)

➡️ Voir SECURITY-AUDIT.md

Performance (Score 7.5/10)

🟡 À améliorer :

• JS/CSS non minifiés (-32 KB possible)
• Pas de Brotli (-7 KB)
• Images PNG 16-bit (-6 KB)
• LocalStorage synchrone (micro-freezes)

➡️ Voir PERFORMANCE-AUDIT.md

---

🤝 Contribution

Workflow de Contribution

1. Fork le repository
2. Clone votre fork
3. Créer une branche : git checkout -b feature/ma-fonctionnalite
4. Développer en suivant les conventions
5. Tester sur staging
6. Committer : git commit -m "v2.X.X - Description"
7. Push : git push origin feature/ma-fonctionnalite
8. Pull Request vers develop

Conventions de Code

PHP :

// camelCase pour variables/fonctions
$familyId = 'famille-denis-mariejo';

// PascalCase pour classes
class UserManager {}

// Commentaires en français
// Récupère les données de la famille

JavaScript :

// camelCase pour variables/fonctions
const currentPerson = 'denis';

// Commentaires en français
// Calcule le total de protéines
function calculateTotal(person) {}

CSS :

/* kebab-case pour classes */
.meal-card {}
.progress-bar {}

/* Variables CSS */
:root {
    --pastel-green: #a8d5ba;
}

Tests

Avant chaque commit :

# Vérifier staging
curl http://51.77.151.209:8083

# Vérifier logs
tail -f /var/log/nginx/proteines-staging-error.log

# Vérifier pas d'erreurs JS
# DevTools Console

---

🔐 Sécurité

Rapporter une Vulnérabilité

NE PAS créer d'issue publique pour les vulnérabilités de sécurité.

Contacter directement :

• Email : [REDACTED]
• Signal : [REDACTED]

Politique de Sécurité

• Correctif : < 48h pour CRITIQUE
• Déploiement : Immédiat après validation
• Notification : Email aux utilisateurs

---

📜 Licence

Propriétaire - Usage personnel famille Denis/Marie Jo

Tous droits réservés. Utilisation, modification et distribution interdites sans autorisation explicite.

---

👨‍💻 Auteurs

• Denis - Créateur et mainteneur principal
• Marie Jo - Utilisatrice et testeur

---

🙏 Remerciements

• Open Food Facts - Base de données alimentaire collaborative
• MongoDB - Base de données NoSQL performante
• Claude Code - Documentation automatisée, audits BMAD
• Communauté PWA - Best practices et inspiration

---

📊 Statistiques du Projet

Métrique	Valeur
Lignes de code	3071
Fichiers	8
Taille totale	120 KB
Taille compressée	31 KB
Versions	19
Aliments base locale	275
Core Web Vitals	✅ Bon
Score Lighthouse	~85

---

🔗 Liens Rapides

Production

• 🌐 Application : http://51.77.151.209:8082
• 📊 API Health : http://51.77.151.209:8082/api/sync.php
• 📝 Logs : /var/log/nginx/proteines-error.log

Staging

• 🔧 Application : http://51.77.151.209:8083
• 📊 API Health : http://51.77.151.209:8083/api/sync.php
• 📝 Logs : /var/log/nginx/proteines-staging-error.log

Documentation

• 📖 Architecture : ARCHITECTURE.md
• 🔒 Sécurité : SECURITY-AUDIT.md
• ⚡ Performance : PERFORMANCE-AUDIT.md
• 📋 Changelog : CHANGELOG.md
• 🔄 Workflow : WORKFLOW.md

Externes

• 🐙 GitHub : git@github.com:Denis1953/proteines.git
• 🍔 Open Food Facts : https://world.openfoodfacts.org/
• 📚 MongoDB Docs : https://docs.mongodb.com/

---

❓ FAQ

Puis-je utiliser l'application hors ligne ?

Oui ! L'application est une PWA avec Service Worker. Après la première visite, elle fonctionne entièrement offline. La synchronisation se fera automatiquement à la prochaine connexion.

Comment ajouter un aliment qui n'existe pas ?

1. Utiliser la recherche et taper le nom
2. Sélectionner "Saisie manuelle"
3. Entrer les protéines/100g
4. Ou créer un aliment personnalisé dans les paramètres

Les données sont-elles sauvegardées ?

Oui, double backup :

• LocalStorage : Sauvegarde locale immédiate
• MongoDB : Sauvegarde cloud automatique

Puis-je utiliser l'application pour une autre famille ?

Actuellement non. L'application est conçue pour une seule famille (Denis/Marie Jo). La version 3.0.0 supportera le multi-familles avec authentification.

Comment mettre à jour l'application ?

Automatique ! Le Service Worker détecte les nouvelles versions et recharge automatiquement l'application.

L'application est-elle sécurisée ?

Partiellement. Voir SECURITY-AUDIT.md pour détails. Les données nutritionnelles ne sont pas sensibles, mais un renforcement de sécurité est prévu en v2.10.0.

---

Dernière mise à jour : 2026-01-22 Version : 2.9.0 Status : ✅ Stable

---

Fait avec ❤️ pour Denis et Marie Jo

⬆ Retour en haut