commit f2144665b7b2fc07a054bcdfacd4fa448c318098 Author: Yugonito Date: Tue Oct 27 17:47:35 2026 +0100 docs: conception de l'outil de finances du foyer Co-Authored-By: Claude Opus 5.5 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e324782 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +.superpowers/ +node_modules/ +.next/ +.env +backups/ +*.log diff --git a/docs/superpowers/specs/2026-10-27-finances-foyer-design.md b/docs/superpowers/specs/2026-10-27-finances-foyer-design.md new file mode 100644 index 0000000..f517532 --- /dev/null +++ b/docs/superpowers/specs/2026-10-27-finances-foyer-design.md @@ -0,0 +1,209 @@ +# 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.