budget-commun/README.md

Budget Commun

Application web PWA pour gérer un budget partagé en couple (ou en famille). Hébergeable sur un NAS ou tout serveur local. Installable sur iPhone/Android depuis Safari/Chrome.

Fonctionnalités :

• Budget commun + budgets personnels par utilisateur
• Dépenses récurrentes (mensuel, hebdo, annuel, ponctuel, paiement en x fois)
• Pointage mensuel des dépenses
• Simulateur de projets d'épargne
• Gestion des épargnes avec suivi du solde
• Thème sombre / clair / système
• Pull-to-refresh sur mobile
• PWA installable (fonctionne hors-ligne en lecture)

---

Stack technique

• Frontend : React + Vite (SPA, PWA)
• Backend : Node.js / Express
• Base de données : PostgreSQL 16
• Authentification : JWT (30 jours)
• Déploiement : Docker / Docker Compose

---

Structure du projet

budget-commun/
├── docker-compose.yml       ← déploiement standard
├── backend/
│   ├── Dockerfile           ← build multi-stage (frontend + backend)
│   ├── server.js            ← API Express + initialisation BDD
│   └── package.json
└── frontend/
    ├── src/
    │   ├── pages/           ← Dashboard, Dépenses, Pointage, Simulateur, Épargnes…
    │   ├── contexts/        ← Auth, Budget, Theme
    │   ├── hooks/
    │   └── api/
    ├── public/
    │   ├── sw.js            ← Service Worker (network-first)
    │   ├── manifest.json
    │   └── favicon.svg
    └── package.json

Le Dockerfile est multi-stage : il build le frontend Vite, puis l'embarque dans l'image Node.js qui sert à la fois l'API et les fichiers statiques sur le port 3000.

---

Démarrage rapide (Docker Compose)

docker compose up -d

L'application est accessible sur http://localhost:3456.

Identifiants par défaut :

Utilisateur	Mot de passe
user1	password1
user2	password2

Sécurité : changez les mots de passe depuis Mon compte → Changer le mot de passe après la première connexion.

---

Configuration

Les variables d'environnement peuvent être définies dans un fichier .env (voir .gitignore) :

Variable	Défaut	Description
DATABASE_URL	postgres://budget:budget@db:5432/budget	Connexion PostgreSQL
JWT_SECRET	budget-commun-secret-change-me	Secret de signature JWT
ADMIN_USER	user1	Nom d'utilisateur administrateur

Pour la production, définissez au minimum JWT_SECRET avec une valeur aléatoire longue.

---

Déploiement sur TrueNAS SCALE (Custom App)

TrueNAS ne supporte pas docker compose directement. Utilisez Custom App via midclt :

1. Charger l'image sur le NAS

Depuis votre machine de build :

# Build pour l'architecture amd64 (TrueNAS)
docker buildx build --platform linux/amd64 -t budget-commun:latest -f backend/Dockerfile .

# Transférer sur le NAS
docker save budget-commun:latest | ssh admin@<IP-NAS> "sudo docker load"

2. Créer l'application

ssh admin@<IP-NAS>

sudo midclt call app.create '{
  "name": "budget-commun",
  "custom_app": true,
  "custom_compose_config": {
    "services": {
      "db": {
        "image": "postgres:16-alpine",
        "restart": "unless-stopped",
        "environment": {
          "POSTGRES_DB": "budget",
          "POSTGRES_USER": "budget",
          "POSTGRES_PASSWORD": "budget"
        },
        "volumes": ["pgdata:/var/lib/postgresql/data"]
      },
      "budget-commun": {
        "image": "budget-commun:latest",
        "restart": "unless-stopped",
        "ports": ["23000:3000"],
        "depends_on": ["db"],
        "environment": {
          "DATABASE_URL": "postgres://budget:budget@db:5432/budget",
          "JWT_SECRET": "changez-cette-valeur"
        }
      }
    },
    "volumes": { "pgdata": {} }
  }
}'

3. Mises à jour

# Rebuild + transfert
docker buildx build --platform linux/amd64 -t budget-commun:latest -f backend/Dockerfile .
docker save budget-commun:latest | ssh admin@<IP-NAS> "sudo docker load"

# Redéployer
ssh admin@<IP-NAS> "sudo midclt call app.redeploy budget-commun"

---

Installation sur mobile (PWA)

iPhone (Safari) :

1. Ouvrir l'URL de l'application dans Safari
2. Appuyer sur Partager → Sur l'écran d'accueil
3. Nommer l'app et confirmer

Android (Chrome) :

1. Ouvrir l'URL dans Chrome
2. Menu → Ajouter à l'écran d'accueil

Les deux appareils doivent être sur le même réseau Wi-Fi que le serveur. Pour un accès depuis l'extérieur, configurez un reverse proxy (Nginx, Traefik) ou un VPN (WireGuard).

---

Développement local

# Backend
cd backend && npm install
DATABASE_URL=postgres://budget:budget@localhost:5432/budget node server.js

# Frontend (dans un autre terminal)
cd frontend && npm install && npm run dev

Le frontend Vite proxifie /api vers http://localhost:3000.

---

Sauvegarde

Les données sont dans le volume Docker pgdata. Pour sauvegarder :

docker exec <container-postgres> pg_dump -U budget budget > backup.sql

Pour restaurer :

docker exec -i <container-postgres> psql -U budget budget < backup.sql