19 KiB
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 viadocker compose. - Base de données : MariaDB
latest(imagemariadb: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(remoteorigin, branchemain). - Langue et formats : interface en français, montants
1 234,56 €, datesJJ/MM/AAAA, fuseauEurope/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 enDECIMAL(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#e5e7ebet coins arrondis (14 px), police Inter ; - couleur d'accent indigo
#4f46e5; vert#059669pour les entrées, rouge#dc2626pour les sorties et les dépassements, ambre#d97706pour 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
- 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.
- Connexion.
- 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 ».
- 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.
- Opérations : liste filtrable (mois, personne, catégorie, type, statut réel/prévu) avec recherche sur le libellé, et édition/suppression.
- 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 ».
- Budgets : un montant mensuel par catégorie, la vue du mois (réel, prévu restant, budget) et un historique sur 6 à 12 mois.
- 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).
- 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).
- 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.
- id, kind (
- 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 »).
- kind, amount, label, categoryId, accountUserId, splits (table RecurringSplit), frequency (
- 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 sipaymentOverrideest saisi (la dernière échéance absorbe l'écart et la date de fin peut alors différer dedurationMonths). (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.)
- Crédit déjà en cours (cas de la voiture) : champs optionnels
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
OperationSplitde 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
PLANNEDsur un horizon glissant de 12 mois à partir du mois courant. La génération est idempotente (index uniquerecurringId + occurrenceDate) et se déclenche à l'ouverture de l'application (ou de chaque page), sans cron. - Si
dayOfMonthdé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 leDockerfile(build Next.jsstandalone, multi-stage), port3000:3000,prisma migrate deployau démarrage ;db:mariadb:latest, volume nommé, healthcheck, non exposé sur l'hôte ;backup: conteneur léger qui lancemariadb-dumpchaque nuit vers./backupssur la VM, en.sql.gzhorodaté, avec une rétention de 30 jours.
- Secrets dans
.env(non commité) et.env.examplefourni : mots de passe de la base, secret de session. - Procédure : sur la VM,
git clonedepuisgit.fabout.it, copier.env.exampleen.env,docker compose up -d --build. Les mises à jour se font pargit pull && docker compose up -d --build. UnREADMEdocumente 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.