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)

```bash
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 :
```bash
# 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

```bash
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

```bash
# 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

```bash
# 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 :

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

Pour restaurer :
```bash
docker exec -i <container-postgres> psql -U budget budget < backup.sql
```