Files
hcl-finances-manager/docs/superpowers/specs/2026-10-27-finances-foyer-design.md
T
2026-10-27 17:47:35 +01:00

210 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Finances du foyer : document de conception
Date : 2026-10-27
Statut : validé en conversation, prêt pour le plan
## 1. Intention
Un couple (deux personnes, deux comptes bancaires perso, **pas de compte joint**) suit aujourd'hui ses finances dans un Google Sheet et dans les applis bancaires. Ils veulent un vrai outil de suivi, auto-hébergé sur leur réseau local, pour :
- que **chacun saisisse ses entrées et dépenses** facilement (téléphone ou ordinateur) ;
- partager les charges en **% entre les deux** et savoir à tout moment **qui doit combien à l'autre** ;
- voir **où rentre et où sort l'argent**, par personne et pour le foyer, mois par mois ;
- **anticiper** grâce aux récurrents, aux dépenses prévues et aux budgets ;
- suivre les **remboursements employeur** (IK, part de loyer) **affectés** à une charge, et ses **crédits**.
C'est un outil **informatif**, sans contrainte : pas d'alerte, pas de culpabilisation, pas de workflow imposé. La réussite, c'est une vue claire et une saisie sans friction.
## 2. Objectifs, non-objectifs, anti-objectifs
**Objectifs (v1)**
- Saisie d'opérations (entrée/dépense) avec payeur, répartition en %, catégorie, date et statut réel/prévu.
- Calcul de l'équilibre entre les personnes (qui doit combien) et enregistrement des remboursements entre elles.
- Tableau de bord mensuel : foyer + flux par personne + équilibre + budgets + charges nettes + dernières opérations.
- Opérations récurrentes (modèles) générant des occurrences prévues, confirmées une fois passées.
- Dépenses/entrées prévues ponctuelles.
- Budgets mensuels par catégorie (prévu vs réel).
- Affectation d'une entrée (remboursement employeur, IK…) à une charge, avec un mode de répartition paramétrable.
- Espace Crédits : mensualité, échéancier, capital restant dû, coût net après affectations.
- Comptes utilisateurs nommés (prénom, couleur), réglages, catégories éditables, export CSV.
**Non-objectifs (v1)**
- Simulateur de crédit et de rentabilité immobilière : **chantier 2**. Une entrée de menu « Simulateur (bientôt) » est simplement prévue.
- Import de relevés bancaires (CSV/OFX) ou synchronisation bancaire.
- Accès depuis Internet, HTTPS, multi-foyer.
- Notifications et alertes.
- Multi-devise (tout est en EUR).
**Anti-objectifs**
- Une interface terne ou peu lisible (la première maquette « gris sur gris » a été rejetée).
- Une saisie mobile qui demande plus de quelques taps pour un cas courant.
- Perdre l'historique (les données doivent être sauvegardées).
## 3. Contraintes
- **Hébergement** : VM locale `192.168.1.211`, vierge avec Docker installé. Tout tourne via `docker compose`.
- **Base de données** : **MariaDB `latest`** (image `mariadb:latest`), volume persistant.
- **Réseau** : accès LAN uniquement, en HTTP sur le port **3000**.
- **Sauvegarde** : dump SQL quotidien côté stack, et la VM entière est sauvegardée par Proxmox Backup Server (PBS, géré par l'utilisateur).
- **Dépôt git** : `git@git.fabout.it:hcloez/hcl-finances-manager.git` (remote `origin`, branche `main`).
- **Langue et formats** : interface en français, montants `1 234,56 €`, dates `JJ/MM/AAAA`, fuseau `Europe/Paris`.
- **Appareils** : usage mixte téléphone et ordinateur, interface responsive.
## 4. Choix techniques (faits par Claude, l'utilisateur les a délégués et approuvés)
- **Next.js (App Router) + TypeScript** : front et API dans un seul projet et un seul conteneur. Mutations par Server Actions ou route handlers, au choix du builder.
- **Prisma** (provider `mysql`, compatible MariaDB) pour le schéma et les migrations. Les migrations s'appliquent au démarrage du conteneur (`prisma migrate deploy`).
- **Tailwind CSS**, composants à la shadcn/ui si utile, police **Inter**. Graphiques avec Recharts si besoin.
- **Authentification** : identifiant + mot de passe (hash argon2 ou bcrypt) et session par cookie httpOnly. Pas de rôles : toute personne connectée voit et modifie tout.
- **Tests** : tests unitaires (Vitest) **obligatoires** sur le moteur de calcul (répartitions, équilibre, flux, affectations, amortissement, génération des récurrents).
- **Montants** : `DECIMAL(12,2)` en base, aucun calcul en float côté code (centimes entiers ou lib décimale). Les pourcentages sont en `DECIMAL(5,2)`.
## 5. Interface (validée sur maquette)
Référence visuelle : `.superpowers/brainstorm/*/content/dashboard-v2.html` (maquette validée par l'utilisateur : « Top là ! »). La reproduire fidèlement en esprit :
- fond clair `#f5f6fa`, cartes blanches avec bordure fine `#e5e7eb` et coins arrondis (14 px), police Inter ;
- couleur d'accent indigo `#4f46e5` ; vert `#059669` pour les entrées, rouge `#dc2626` pour les sorties et les dépassements, ambre `#d97706` pour le « prévu » et le bandeau d'équilibre ;
- **une couleur par personne** (choisie en réglages, par défaut indigo et rose `#db2777`), reprise dans les avatars et les badges « payé par » ;
- barre latérale de navigation sur ordinateur, navigation en bas ou dans un menu sur mobile ;
- partout, les **prénoms** remplacent « Toi » et « Conjointe ». La vue reste la même quel que soit l'utilisateur connecté, mais on peut dire « Léa te doit 450 € » du point de vue de la personne connectée.
### Écrans
1. **Installation (premier lancement)** : s'il n'existe aucun utilisateur, un écran crée les deux comptes (prénom, identifiant, mot de passe, couleur) et propose la répartition par défaut (50/50). Ensuite, cet écran n'est plus accessible.
2. **Connexion.**
3. **Tableau de bord** (mois sélectionnable ‹ › ; la structure suit la maquette) :
- 3 cartes foyer : Entrées, Sorties, Reste (voir §7) ;
- bandeau d'équilibre : « X doit N € à Y » + bouton « Enregistrer un remboursement » ;
- une carte par personne : Entrées, Payé de sa poche, Part réelle des charges, Reste ;
- budgets du mois (barres, en rouge si dépassement) ;
- charges nettes : chaque charge ayant au moins une affectation, avec brut − remboursements = net et la répartition ;
- dernières opérations, les prévues en atténué avec un badge « prévue ».
4. **Saisie rapide** (modale ou page, optimisée mobile, cf. maquette) : bascule Dépense/Entrée, montant en grand, libellé, catégorie en pastilles, payeur, répartition en pastilles (50/50, 100 % A, 100 % B, Perso…), date (aujourd'hui par défaut). Section repliée « + » : statut prévu, rendre récurrent, affecter à une charge, note. Le payeur est pré-sélectionné sur la personne connectée.
5. **Opérations** : liste filtrable (mois, personne, catégorie, type, statut réel/prévu) avec recherche sur le libellé, et édition/suppression.
6. **Récurrents & prévu** :
- la liste des modèles récurrents (création, édition, pause, fin) ;
- la liste des opérations prévues à venir, avec l'action « Confirmer » (montant et date ajustables) ou « Ignorer cette occurrence ».
7. **Budgets** : un montant mensuel par catégorie, la vue du mois (réel, prévu restant, budget) et un historique sur 6 à 12 mois.
8. **Crédits & charges** : la liste des crédits, puis le détail d'un crédit (paramètres, échéancier complet, capital restant dû à date, intérêts payés et restants, affectations et coût net).
9. **Réglages** : utilisateurs (prénom, couleur, mot de passe), répartition par défaut, catégories (CRUD, emoji, type entrée/dépense, archivage), export CSV des opérations (période au choix).
10. **Simulateur** : entrée de menu désactivée « bientôt ».
## 6. Modèle de données (indicatif, le builder peut ajuster les noms)
- **User** : id, firstName, login (unique), passwordHash, color, createdAt.
- **Settings** (singleton) : defaultSplit (JSON `{userId: pct}`).
- **Category** : id, name, emoji, kind (`INCOME` | `EXPENSE`), archived. Une liste de départ est créée par seed (voir §10).
- **Operation** :
- id, kind (`INCOME` | `EXPENSE`), amount (> 0), date, label, categoryId, note ;
- **accountUserId** : la personne dont le compte est débité (dépense) ou crédité (entrée), c'est-à-dire le « payeur » ou le « receveur » ;
- status (`PLANNED` | `ACTUAL`) ;
- recurringId (nullable) + occurrenceDate (nullable), avec un index unique (recurringId, occurrenceDate) ;
- **allocatedToRecurringId** (nullable) ou **allocatedToOperationId** (nullable, dépense ponctuelle) : l'affectation d'une entrée à une charge (voir §8). Au plus un des deux est renseigné ;
- allocationMode (nullable : `REDUCE_SHARED` | `BENEFICIARY_ONLY` | `CUSTOM`) ;
- createdById, createdAt, updatedAt.
- **OperationSplit** : operationId, userId, percent. La somme vaut 100 par opération. C'est la part **économique** de chacun (qui supporte la dépense, à qui profite l'entrée).
- **Recurring** (modèle) :
- kind, amount, label, categoryId, accountUserId, splits (table RecurringSplit), frequency (`MONTHLY` | `QUARTERLY` | `YEARLY`), dayOfMonth, startDate, endDate (nullable), paused ;
- loanId (nullable, si le récurrent est la mensualité d'un crédit) ;
- allocatedToRecurringId + allocationMode (un récurrent d'entrée peut lui-même être affecté, par exemple « Part loyer employeur » → « Loyer »).
- **Settlement** (remboursement entre personnes) : id, fromUserId, toUserId, amount, date, note.
- **Budget** : categoryId, monthlyAmount, startMonth (YYYY-MM), endMonth (nullable). Un seul budget actif par catégorie et par mois.
- **Loan** : id, name, lender, principal, annualRate (%), durationMonths, startDate (première échéance), insuranceMonthly (montant fixe, défaut 0), accountUserId (titulaire), splits (LoanSplit). La création d'un Loan crée son Recurring de mensualité (montant = échéance + assurance, catégorie « Crédit »).
- **Crédit déjà en cours** (cas de la voiture) : champs optionnels `paymentOverride` (mensualité hors assurance réelle, telle que la banque l'indique), `referenceDate` + `referenceRemainingCapital` (capital restant dû constaté à une date). Si la référence est renseignée, l'échéancier est recalculé **à partir de cette date et de ce capital** (lignes antérieures non affichées / marquées « avant suivi »), avec la mensualité forcée si `paymentOverride` est saisi (la dernière échéance absorbe l'écart et la date de fin peut alors différer de `durationMonths`). *(Choix de Claude, suite au « je vais tout indiquer moi-même » de l'utilisateur : coller aux chiffres de la banque sans importer d'échéancier.)*
## 7. Règles de calcul
Notations, pour une opération `o` : montant `A`, compte `acc(o)`, part `s_P(o)` de la personne P (en fraction de 1).
**Répartition par défaut à la saisie** *(choix de Claude)* : une **dépense** reçoit la répartition par défaut du foyer (Settings, 50/50 au départ). Une **entrée** est à **100 % pour la personne qui la reçoit** (`acc`) : un salaire n'est jamais partagé par erreur. Une entrée affectée suit le mode d'affectation (§8). Dans tous les cas, on peut passer en « Perso… ».
**Point de départ** : l'application démarre vide, sans import de l'historique Google Sheet. L'écran d'installation propose un **solde d'ouverture** facultatif entre les deux personnes, enregistré comme un Settlement daté du jour. Les récurrents et les crédits dont la date de début est passée **ne génèrent pas** d'occurrences rétroactives : la génération commence au mois courant.
**Arrondis** : la part en euros de chaque personne est arrondie au centime. Le résidu d'arrondi est attribué à la personne `acc(o)`, pour que la somme des parts soit toujours exactement `A`.
### 7.1 Équilibre entre personnes (qui doit combien)
Il se calcule sur **toutes les opérations `ACTUAL` depuis l'origine** (les prévues sont exclues), plus les remboursements entre personnes :
- dépense : `solde(P) += A × ([acc = P] − s_P)`. Avoir payé pour les autres rend créancier ;
- entrée : `solde(P) += A × (s_P − [acc = P])`. Avoir reçu de l'argent qui revient en partie aux autres rend débiteur ;
- remboursement de F vers T, montant M : `solde(F) += M`, `solde(T) −= M`.
`solde(P) > 0` signifie qu'on doit de l'argent à P. Avec deux personnes, on affiche « [débiteur] doit |solde| € à [créancier] », ou « Vous êtes à l'équilibre » si le solde vaut 0.
L'écran indique aussi la date du dernier remboursement.
*Exemple de contrôle* : loyer 1 000 € payé par H, réparti 50/50, donc H +500. Remboursement employeur de 200 € reçu par H, affecté au loyer en mode REDUCE_SHARED (donc réparti 50/50) : H −100. Au total, C doit 400 € à H, ce qui correspond bien au loyer net de 800 € réparti 400/400.
### 7.2 Flux mensuels
Pour un mois M, l'onglet par personne P porte sur les opérations `ACTUAL`. Les cartes foyer incluent les `PLANNED` du mois dans la ligne « dont X € prévus » et dans le « Reste après prévues ».
- **Entrées(P)** = Σ entrées où `acc = P` (l'argent arrivé sur son compte).
- **Payé de sa poche(P)** = Σ dépenses où `acc = P`.
- **Part réelle des charges(P)** = Σ dépenses × `s_P` − Σ entrées **affectées** × `s_P`.
- **Revenus propres(P)** = Σ entrées **non affectées** × `s_P`.
- **Reste(P)** = Revenus propres(P) − Part réelle des charges(P).
- **Foyer** : Entrées = Σ entrées (dont « remboursés par l'employeur » = Σ entrées affectées), Sorties = Σ dépenses (dont « prévus » = Σ dépenses PLANNED du mois), Reste = Entrées − Sorties, prévues incluses.
### 7.3 Charges nettes (affectations)
Pour chaque charge (Recurring de type EXPENSE) cible d'au moins une affectation dans le mois : brut = Σ occurrences de la charge dans le mois, remboursé = Σ entrées affectées à cette charge dans le mois, net = brut − remboursé. La répartition affichée est celle de la charge.
### 7.4 Budgets
Pour chaque catégorie budgétée sur le mois : réel = Σ dépenses ACTUAL de la catégorie (montant total du foyer, sans répartition), prévu restant = Σ dépenses PLANNED de la catégorie dans le mois. La barre passe en rouge si réel > budget. Les dépenses sans budget n'apparaissent pas dans ce bloc.
### 7.5 Crédits (amortissement)
Amortissement français à mensualités constantes : `m = P × r / (1 − (1 + r)^−n)` avec `r = taux annuel / 12`. Si le taux vaut 0, `m = P / n`. L'échéancier ligne à ligne donne la date, l'échéance, les intérêts, le capital, l'assurance et le capital restant dû. L'arrondi se fait au centime à chaque ligne, et la dernière échéance absorbe le résidu. Le capital restant dû « à date » est celui après la dernière échéance passée. Le coût net mensuel est l'échéance + assurance − les entrées affectées au récurrent du crédit sur le mois.
## 8. Affectations (remboursements employeur, IK…)
- Une **entrée** (ou un récurrent d'entrée) peut être affectée à une **charge** : soit un Recurring de dépense (ce qui inclut les mensualités de crédit), soit une **dépense ponctuelle** (note de frais qui rembourse un hôtel, un billet de train…). *(Choix de Claude.)* Dans le §7.3, une dépense ponctuelle affectée apparaît comme une charge à part dans le mois de la dépense.
- Le mode d'affectation détermine les `OperationSplit` de l'entrée :
- **REDUCE_SHARED** (par défaut, « option B » choisie par l'utilisateur) : les parts de l'entrée **copient la répartition de la charge**. Le remboursement réduit la charge avant le partage ;
- **BENEFICIARY_ONLY** (« option A ») : 100 % pour la personne qui reçoit l'entrée ;
- **CUSTOM** : des % saisis librement.
- Quand on choisit une affectation dans le formulaire, les parts sont pré-remplies selon le mode et restent modifiables (passer en CUSTOM).
- Cas réels à couvrir :
- « IK » (entrée récurrente ou ponctuelle, reçue par H) → « Crédit voiture » (titulaire H, 100 % H) ;
- « Part loyer employeur » (reçue par H) → « Loyer » (50/50), en mode REDUCE_SHARED.
## 9. Récurrents et prévu
- **Génération** : les occurrences d'un Recurring sont matérialisées en Operation `PLANNED` sur un horizon glissant de **12 mois** à partir du mois courant. La génération est idempotente (index unique `recurringId + occurrenceDate`) et se déclenche à l'ouverture de l'application (ou de chaque page), sans cron.
- Si `dayOfMonth` dépasse le nombre de jours du mois, l'occurrence tombe le dernier jour du mois.
- **Confirmation** : une occurrence PLANNED dont la date est passée apparaît dans « À confirmer » (Récurrents & prévu, plus un compteur discret sur le tableau de bord). Le bouton « Confirmer » la passe en ACTUAL, avec un montant et une date ajustables. « Ignorer » la supprime et mémorise l'occurrence pour qu'elle ne soit pas régénérée (par exemple via une table de skip ou un statut `SKIPPED`, au choix du builder).
Aucune auto-confirmation en v1. *(Choix de Claude : rester fidèle au réel sans ressaisie.)*
- **Modification d'un modèle** : elle s'applique aux occurrences PLANNED futures (≥ aujourd'hui), pas aux ACTUAL ni aux PLANNED passées non confirmées.
- **Pause ou fin** : les PLANNED futures sont supprimées.
- **Dépense prévue ponctuelle** : une Operation PLANNED sans recurringId, qui suit la même logique de confirmation.
## 10. Données de départ (seed)
- **Catégories de dépense** : Logement 🏠, Courses 🛒, Restaurants 🍽, Transport ⛽, Auto 🚗, Crédit 🏦, Énergie ⚡, Télécom 📱, Abonnements 📺, Santé 💊, Loisirs 🎉, Vacances ✈️, Vêtements 👕, Cadeaux 🎁, Maison 🛋, Impôts 🧾, Divers 📦.
- **Catégories d'entrée** : Salaire 💼, Remboursement employeur 🧾, IK 🚗, Prime 💶, Autres revenus ➕.
- Aucune donnée fictive en production.
## 11. Déploiement et exploitation
- Fichier `docker-compose.yml` à la racine avec trois services :
- `app` : image construite depuis le `Dockerfile` (build Next.js `standalone`, multi-stage), port `3000:3000`, `prisma migrate deploy` au démarrage ;
- `db` : `mariadb:latest`, volume nommé, healthcheck, non exposé sur l'hôte ;
- `backup` : conteneur léger qui lance `mariadb-dump` chaque nuit vers `./backups` sur la VM, en `.sql.gz` horodaté, avec une **rétention de 30 jours**.
- Secrets dans `.env` (non commité) et `.env.example` fourni : mots de passe de la base, secret de session.
- **Procédure** : sur la VM, `git clone` depuis `git.fabout.it`, copier `.env.example` en `.env`, `docker compose up -d --build`. Les mises à jour se font par `git pull && docker compose up -d --build`. Un `README` documente l'installation, la mise à jour, la restauration d'un dump et la réinitialisation d'un mot de passe oublié (commande CLI ou script dans le conteneur).
- `.superpowers/` est ajouté à `.gitignore`.
## 12. Laissé au builder
- La structure du code, les noms exacts, le choix entre Server Actions et route handlers, la bibliothèque de session, la bibliothèque décimale.
- Le détail visuel des écrans non maquettés (Opérations, Récurrents, Budgets, Crédits, Réglages), dans le même langage visuel que la maquette validée.
- La navigation mobile (barre en bas ou menu).
- Le format exact de l'export CSV (séparateur `;`, décimales à virgule, UTF-8 avec BOM pour Excel recommandés).
## 13. Chantier 2 (hors v1, pour mémoire)
Simulateur de crédit et de rentabilité immobilière : mensualité, coût total, assurance, tableau d'amortissement, frais de notaire, rendement brut/net, cash-flow, fiscalité (LMNP / foncier), vacance locative. Il réutilisera le moteur d'amortissement du §7.5. Il fera l'objet d'une discussion dédiée.