# 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.