Files
hcl-finances-manager/docs/superpowers/plans/2026-10-27-finances-foyer-v1.md
T
2026-10-27 17:52:19 +01:00

738 lines
54 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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 v1 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Build a self-hosted household finance tracker for two people, with shared expenses split in %, a running "who owes whom" balance, recurring and planned operations, budgets, employer reimbursements linked to the charge they offset, and loans. It is deployed with docker compose (Next.js + MariaDB) on a LAN VM.
**Architecture:** A single Next.js App Router project in TypeScript. All financial logic lives in a pure, unit-tested `src/domain/` layer that works in integer cents, basis points and ISO date strings. `src/server/` holds the thin Prisma repositories, auth, and the Server Actions that map DB rows to domain types. `src/app/` holds the pages, built with Tailwind in the visual language of the validated mockup. Recurring occurrences are created idempotently when a page loads, so there is no cron job.
**Tech Stack:**
- Node 24, Next.js 15 (App Router, `output: 'standalone'`), React 19, TypeScript strict, Tailwind CSS 4
- Prisma 6 (provider `mysql`) on `mariadb:latest`
- Vitest, `iron-session`, `bcryptjs`, `zod`, `recharts`
- Docker compose
**Spec:** `docs/superpowers/specs/2026-10-27-finances-foyer-design.md`. Read it before any task, because section numbers (§) below refer to it. Visual reference: `.superpowers/brainstorm/250-1793118883/content/dashboard-v2.html`.
## Global Constraints
- The UI is in French. Amounts display as `1 234,56 €` (`Intl.NumberFormat('fr-FR',{style:'currency',currency:'EUR'})`) and dates as `JJ/MM/AAAA`. The timezone is `Europe/Paris`.
- Amounts are `DECIMAL(12,2)` in the DB. The domain works in **integer cents**. No float arithmetic on money, anywhere.
- Splits are integer **basis points** (100 % = 10000). A split is valid only if it sums to exactly 10000 and every value is ≥ 0.
- Dates in the domain are `YYYY-MM-DD` strings and months are `YYYY-MM` strings. Never use a JS `Date` for day or month logic, so UTC/Paris drift is impossible.
- Colors: bg `#f5f6fa`, card `#ffffff`, line `#e5e7eb`, text `#111827`, muted `#6b7280`, accent `#4f46e5`, green `#059669`, red `#dc2626`, amber `#d97706`. Default person colors are `#4f46e5` and `#db2777`. Font is Inter, card radius is 14px.
- The DB is `mariadb:latest`. The app is reachable on port `3000` and the DB is not exposed on the host.
- First names replace "Toi/Conjointe" everywhere.
- Status `SKIPPED` exists only to stop a recurring occurrence from regenerating. Every calculation ignores it.
- Commit messages end with `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`.
## Review Focus
1. **Splits that don't sum to 100 %, or are uneven.** 33.33/66.67 must be accepted, 33.33/33.33 rejected with a French error message, and the cent residue assigned to the account holder. Tests are in Task 2.
2. **French amount input.** `86,40`, `86.40`, `1 234,56` and `1 234,56` (narrow nbsp) must all parse to cents. `0`, `-5` and `abc` must be rejected. Tests are in Task 2.
3. **Recurring day 31 or 29.** It must fall on the last day of short months (2027-02-28). Quarterly and yearly items step from the start date's month. Tests are in Task 6.
4. **Deleting things that other things point to.** Deleting a recurring template or an allocation target must not delete ACTUAL history or crash. The references are set to NULL. Tests are in Task 9 (repository integration test) and Task 6 (pure planning ignores a missing target).
5. **Month boundaries.** An operation dated `2026-10-31` belongs to October whatever the server timezone. The default month is computed in Europe/Paris. Tests are in Task 4 (`monthOf`) and Task 1 (`todayParis`).
---
## File Structure
```
package.json, tsconfig.json, next.config.ts, vitest.config.ts, postcss.config.mjs, .env.example
prisma/schema.prisma # full schema (Task 1)
prisma/seed.ts # categories + settings singleton (Task 1)
src/lib/dates.ts # ISO date helpers, todayParis, month math (Task 1)
src/domain/types.ts # domain types (Task 2)
src/domain/money.ts # parse/format cents, splits (Task 2)
src/domain/balance.ts # who owes whom (Task 3)
src/domain/monthly.ts # per-person flows, household totals, net charges, budgets (Task 4)
src/domain/loan.ts # amortization (Task 5)
src/domain/recurrence.ts # occurrence dates + planning (Task 6)
src/server/db.ts # Prisma singleton (Task 1)
src/server/auth.ts # session, requireUser, password hashing (Task 7)
src/server/mappers.ts # Prisma row -> domain (Task 8)
src/server/repo.ts # data loading used by pages (Task 8)
src/server/sync.ts # syncRecurrings() (Task 8)
src/server/actions/*.ts # setup/auth, operations, settlements, recurrings, budgets, loans, settings
src/app/(public)/setup, login # Task 7
src/app/(app)/layout.tsx # shell with sidebar + mobile nav (Task 8)
src/app/(app)/page.tsx # dashboard (Task 10)
src/app/(app)/operations, recurrents, budgets, credits, credits/[id], reglages # Tasks 11-15
src/app/api/export/route.ts # CSV (Task 15)
src/components/ui/*.tsx # Card, Chip, Avatar, Button, MonthSwitcher, Field, Pills (Task 8)
src/components/OperationForm.tsx # quick entry (Task 9)
tests/domain/*.test.ts # unit tests
tests/server/*.test.ts # integration tests against local MariaDB (TEST_DATABASE_URL)
Dockerfile, docker-compose.yml, docker-compose.dev.yml, docker/entrypoint.sh, docker/backup.sh
scripts/reset-password.ts, README.md
```
---
### Task 1: Project scaffold, schema, local DB
**Files:**
- Create: everything under "scaffold" in File Structure, plus `prisma/schema.prisma`, `prisma/seed.ts`, `src/lib/dates.ts`, `src/server/db.ts`, `docker-compose.dev.yml`, `.env.example`
- Test: `tests/lib/dates.test.ts`
**Interfaces:**
- Produces:
- `src/lib/dates.ts`:
- `todayParis(now?: Date): string` returns YYYY-MM-DD
- `currentMonthParis(now?: Date): string` returns YYYY-MM
- `monthOf(iso: string): string`
- `addMonths(month: string, n: number): string`
- `daysInMonth(month: string): number`
- `toIsoDate(d: Date): string` (reads UTC parts, for Prisma `@db.Date` values)
- `fromIsoDate(iso: string): Date` (UTC midnight)
- `formatDateFr(iso: string): string` returns JJ/MM/AAAA
- `monthLabelFr(month: string): string` returns "Octobre 2026"
- The Prisma client `prisma` from `src/server/db.ts`.
- The DB schema below.
- [ ] **Step 1: Scaffold.** Run `npx create-next-app@15 . --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm --no-turbopack` (keep the existing `docs/` and `.gitignore`). Then:
- install `prisma@6 @prisma/client@6 iron-session bcryptjs zod recharts`;
- install as dev dependencies `vitest @types/bcryptjs tsx`;
- set `output: 'standalone'` in `next.config.ts`;
- add the scripts `"test": "vitest run"`, `"db:migrate": "prisma migrate dev"` and `"db:seed": "tsx prisma/seed.ts"`, and `"prisma": {"seed": "tsx prisma/seed.ts"}`;
- in `vitest.config.ts`, use the alias `@` → `src` and the environment `node`.
- [ ] **Step 2: Dev DB.** In `docker-compose.dev.yml`, add a `mariadb:latest` service on host port `3307`. Use the env vars `MARIADB_ROOT_PASSWORD=dev` and `MARIADB_DATABASE=finances`, and an init SQL that also creates `finances_test`. In `.env.example`, put:
```
DATABASE_URL="mysql://root:dev@localhost:3307/finances"
TEST_DATABASE_URL="mysql://root:dev@localhost:3307/finances_test"
SESSION_SECRET="change-me-to-32+chars-random-string-xxxxxxxx"
```
Copy it to `.env`, then run `docker compose -f docker-compose.dev.yml up -d`.
- [ ] **Step 3: Write `prisma/schema.prisma`.**
- Enums:
- `OpKind {INCOME EXPENSE}`
- `OpStatus {PLANNED ACTUAL SKIPPED}`
- `AllocationMode {REDUCE_SHARED BENEFICIARY_ONLY CUSTOM}`
- `Frequency {MONTHLY QUARTERLY YEARLY}`
- Models: ids are `String @id @default(cuid())` unless stated. Money fields are `Decimal @db.Decimal(12,2)`, date fields are `DateTime @db.Date`, and splits use `basisPoints Int`.
- `User`: firstName, login @unique, passwordHash, color, createdAt.
- `Setting`: `id Int @id @default(1)`, `defaultSplit Json` (a map userId→bp).
- `Category`: name, emoji, kind OpKind, archived Bool default false, sortOrder Int default 0.
- `Operation`:
- kind, amount, date, label, note `String? @db.Text`, categoryId → Category (onDelete Restrict), accountUserId → User, status ;
- recurringId? → Recurring (**onDelete SetNull**), occurrenceDate? (Date) ;
- allocatedToRecurringId? → Recurring (**SetNull**), allocatedToOperationId? → Operation (self relation, **SetNull**, NoAction on update), allocationMode? ;
- createdById → User, createdAt, updatedAt ;
- `@@unique([recurringId, occurrenceDate])`, `@@index([date])`.
- `OperationSplit`: operationId (onDelete **Cascade**), userId, basisPoints, `@@id([operationId,userId])`.
- `Recurring`:
- kind, amount, label, categoryId, accountUserId, frequency, dayOfMonth Int, startDate, endDate?, paused Bool default false ;
- loanId? @unique → Loan (onDelete **Cascade**) ;
- allocatedToRecurringId? → Recurring (self, SetNull), allocationMode? ;
- splits `RecurringSplit[]`.
- `RecurringSplit`: recurringId (Cascade), userId, basisPoints, `@@id([recurringId,userId])`.
- `Settlement`: fromUserId, toUserId, amount, date, note?, createdAt.
- `Budget`: categoryId (Cascade), monthlyAmount, `startMonth String @db.Char(7)`, `endMonth String? @db.Char(7)`.
- `Loan`: name, lender?, principal, `annualRate Decimal @db.Decimal(6,3)`, durationMonths Int, startDate, insuranceMonthly default 0, accountUserId, paymentOverride?, referenceDate?, referenceRemainingCapital?, splits `LoanSplit[]`, recurring `Recurring?`.
- `LoanSplit`: loanId (Cascade), userId, basisPoints, `@@id([loanId,userId])`.
- [ ] **Step 4: Seed.** `prisma/seed.ts` upserts the categories of spec §10 (exact names and emojis, kind EXPENSE or INCOME, with sortOrder in list order) by name+kind. It also upserts `Setting{id:1, defaultSplit:{}}`, which gets filled at setup. It creates no users. Run `npx prisma migrate dev --name init`, then `npm run db:seed`.
Expected: the migration applies and `SELECT COUNT(*) FROM Category` returns 22.
- [ ] **Step 5: Write the failing tests** in `tests/lib/dates.test.ts`:
```ts
expect(todayParis(new Date('2026-10-31T23:30:00Z'))).toBe('2026-11-01'); // Paris is UTC+1 after DST ends
expect(todayParis(new Date('2026-10-31T22:30:00Z'))).toBe('2026-10-31');
expect(monthOf('2026-10-31')).toBe('2026-10');
expect(addMonths('2026-11', 3)).toBe('2027-02');
expect(addMonths('2026-01', -1)).toBe('2025-12');
expect(daysInMonth('2028-02')).toBe(29);
expect(toIsoDate(new Date('2026-10-31T00:00:00Z'))).toBe('2026-10-31');
expect(formatDateFr('2026-10-05')).toBe('05/10/2026');
expect(monthLabelFr('2026-10')).toBe('Octobre 2026');
```
- [ ] **Step 6: Run** `npx vitest run tests/lib`. Expected: FAIL (module missing).
- [ ] **Step 7: Implement `src/lib/dates.ts`.** Use `Intl.DateTimeFormat('en-CA',{timeZone:'Europe/Paris'})` for `todayParis`. Everything else is string arithmetic.
- [ ] **Step 8: Run** `npx vitest run tests/lib` and `npm run build`. Expected: both PASS.
- [ ] **Step 9: Commit** with `chore: scaffold Next.js + Prisma schema + dev MariaDB`.
---
### Task 2: Domain types, money and splits
**Files:**
- Create: `src/domain/types.ts`, `src/domain/money.ts`
- Test: `tests/domain/money.test.ts`
**Interfaces:**
- Produces `src/domain/types.ts`:
```ts
export type Cents = number; export type UserId = string;
export type Split = Record<UserId, number>; // basis points, sum 10000
export type OpKind = 'INCOME' | 'EXPENSE';
export type OpStatus = 'PLANNED' | 'ACTUAL' | 'SKIPPED';
export type AllocationMode = 'REDUCE_SHARED' | 'BENEFICIARY_ONLY' | 'CUSTOM';
export interface Op { id: string; kind: OpKind; amount: Cents; date: string; label: string;
categoryId: string; accountUserId: UserId; status: OpStatus; split: Split;
recurringId: string | null; allocatedToRecurringId: string | null;
allocatedToOperationId: string | null; allocationMode: AllocationMode | null; }
export interface Settlement { id: string; fromUserId: UserId; toUserId: UserId; amount: Cents; date: string; }
```
- Produces `src/domain/money.ts`:
- `parseEuro(input: string): Cents | null`: returns null for empty, ≤0 or invalid input.
- `formatEuro(c: Cents, opts?: {sign?: boolean}): string`
- `centsFromDecimal(d: {toString(): string} | string | number): Cents`
- `decimalFromCents(c: Cents): string` (for example `"86.40"`)
- `validateSplit(s: Split): string | null`: returns the French error message or null.
- `shareAmounts(amount: Cents, split: Split, accountUserId: UserId): Record<UserId, Cents>`
- `percentToBp(input: string): number | null` (`"33,33"` gives 3333)
- `bpToPercentLabel(bp: number): string` (5000 gives `"50"`, 3333 gives `"33,33"`)
- `fullSplit(userId: UserId, userIds: UserId[]): Split`: 10000 for one user, 0 for the others.
- [ ] **Step 1: Write the failing tests.**
```ts
for (const s of ['86,40','86.40','1 234,56','1 234,56','1234']) expect(parseEuro(s)).not.toBeNull();
expect(parseEuro('86,40')).toBe(8640); expect(parseEuro('1 234,56')).toBe(123456); expect(parseEuro('1234')).toBe(123400);
for (const s of ['','0','-5','abc','12,345']) expect(parseEuro(s)).toBeNull();
expect(formatEuro(123456)).toBe('1 234,56 €'); // Intl fr-FR output
expect(formatEuro(-8640, {sign:true})).toBe('−86,40 €'); expect(formatEuro(500, {sign:true})).toBe('+5,00 €');
expect(centsFromDecimal('86.40')).toBe(8640); expect(decimalFromCents(8640)).toBe('86.40');
expect(validateSplit({a:5000,b:5000})).toBeNull();
expect(validateSplit({a:3333,b:6667})).toBeNull();
expect(validateSplit({a:3333,b:3333})).toBe('La répartition doit totaliser 100 %.');
expect(validateSplit({a:-100,b:10100})).toBe('Les pourcentages doivent être positifs.');
expect(shareAmounts(1000, {a:3333,b:6667}, 'a')).toEqual({a:334, b:666}); // residue to account holder
expect(shareAmounts(8640, {a:5000,b:5000}, 'b')).toEqual({a:4320, b:4320});
expect(shareAmounts(1, {a:5000,b:5000}, 'b')).toEqual({a:0, b:1});
expect(percentToBp('33,33')).toBe(3333); expect(bpToPercentLabel(3333)).toBe('33,33'); expect(bpToPercentLabel(5000)).toBe('50');
expect(fullSplit('a',['a','b'])).toEqual({a:10000,b:0});
```
If `Intl` emits a different space character for `formatEuro`, assert against the `Intl` output instead. The sign must be the real minus `−` (U+2212), as in the mockup.
- [ ] **Step 2: Run** `npx vitest run tests/domain/money.test.ts`. Expected: FAIL.
- [ ] **Step 3: Implement.** In `shareAmounts`, round each share with `Math.floor(amount*bp/10000)` on integers, then add `amount − Σ` to `accountUserId`. In `parseEuro`, strip the spaces (`\s`, U+00A0, U+202F), replace `,` with `.`, and match `/^\d+(\.\d{1,2})?$/`.
- [ ] **Step 4: Run** the tests. Expected: PASS.
- [ ] **Step 5: Commit** with `feat(domain): money parsing/formatting and splits`.
---
### Task 3: Balance between people (spec §7.1)
**Files:**
- Create: `src/domain/balance.ts`
- Test: `tests/domain/balance.test.ts`
**Interfaces:**
- Consumes: `Op`, `Settlement`, `shareAmounts`.
- Produces:
- `computeBalances(ops: Op[], settlements: Settlement[], userIds: UserId[]): Record<UserId, Cents>`: only ACTUAL ops count. A positive value means P is owed.
- `describeBalance(b: Record<UserId, Cents>): {debtor: UserId; creditor: UserId; amount: Cents} | null`: built for two people, returns null when every value is 0.
- [ ] **Step 1: Write the failing tests.** Use a helper `op(partial)` that builds an `Op` with defaults (status ACTUAL, split 50/50, allocation null).
- Spec control example: rent EXPENSE 100000, acc H, split 50/50, plus INCOME 20000 acc H, split 50/50 (REDUCE_SHARED copy). Expect `computeBalances(...)` to equal `{H: 40000, C: -40000}`, and `describeBalance` to return `{debtor:'C', creditor:'H', amount:40000}`.
- Salary INCOME 300000, acc H, split `{H:10000,C:0}` gives `{H:0,C:0}`, and `describeBalance` returns null.
- A PLANNED or SKIPPED expense is ignored.
- Settlement C→H 40000 on top of the control example gives `{H:0, C:0}`.
- An uneven split of 1000 at 3333/6667, acc H, gives `{H:666, C:-666}`. This uses `shareAmounts`, so the shares are a:334 and b:666.
- [ ] **Step 2: Run** the tests. Expected: FAIL.
- [ ] **Step 3: Implement** with the formulas of §7.1, using the `shareAmounts` cents (not float).
- [ ] **Step 4: Run** the tests. Expected: PASS.
- [ ] **Step 5: Commit** with `feat(domain): balance between people`.
---
### Task 4: Monthly flows, household totals, net charges, budgets (spec §7.2–7.4)
**Files:**
- Create: `src/domain/monthly.ts`
- Test: `tests/domain/monthly.test.ts`
**Interfaces:**
- Consumes: `Op`, `shareAmounts`, `monthOf`.
- Produces:
- `personFlows(ops: Op[], month: string, userId: UserId): {income: Cents; paidOut: Cents; chargesShare: Cents; ownIncome: Cents; remaining: Cents}`. It uses ACTUAL ops of the month only. An "allocated" income is an INCOME with `allocatedToRecurringId` or `allocatedToOperationId` set.
- `householdTotals(ops: Op[], month: string): {income: Cents; allocatedIncome: Cents; plannedIncome: Cents; expense: Cents; plannedExpense: Cents; remaining: Cents}`. Here `income` and `expense` cover ACTUAL + PLANNED, and `remaining = income − expense`.
- `netCharges(ops: Op[], month: string, charges: {id: string; label: string; kind: 'recurring'|'operation'; split: Split}[]): {id; label; gross: Cents; reimbursed: Cents; net: Cents; split: Split}[]`. It lists only the charges that have at least one allocated income in the month.
- For a recurring charge, gross = Σ non-SKIPPED occurrences (ACTUAL + PLANNED) with that `recurringId` in the month.
- For an operation charge, gross = that op's amount when it falls in the month.
- reimbursed = Σ non-SKIPPED incomes allocated to the charge in the month.
- `budgetStatus(ops: Op[], month: string, budgets: {categoryId: string; amount: Cents}[]): {categoryId; budget: Cents; actual: Cents; plannedRemaining: Cents; over: boolean}[]`.
- `budgetForMonth(budgets: {categoryId; monthlyAmount: Cents; startMonth; endMonth: string|null}[], month: string): {categoryId; amount: Cents}[]`. When several budgets match, the latest `startMonth` wins.
- [ ] **Step 1: Write the failing tests.** The fixture is October 2026 with users H and C. The figures reproduce the mockup's structure with simple numbers.
- Ops:
- salary H +300000 (100 % H) on 10-25 ;
- salary C +200000 (100 % C) ;
- rent −100000 acc H 50/50 (recurringId `rent`) ;
- employer rent +20000 acc H, allocated to `rent`, split 50/50 ;
- car loan −38000 acc H 100 % H (recurringId `car`) ;
- IK +22000 acc H, allocated to `car`, 100 % H ;
- groceries −8640 acc C 50/50 ACTUAL ;
- PLANNED car service −35000 acc H 100 % H on 10-30 ;
- an op dated `2026-11-01`, which is excluded.
- `personFlows(ops,'2026-10','H')`:
- income = 300000+20000+22000 = 342000 ;
- paidOut = 100000+38000 = 138000 ;
- chargesShare = 50000+38000+4320 − 10000 − 22000 = 60320 ;
- ownIncome = 300000 ;
- remaining = 239680.
- `personFlows(...,'C')`: income 200000, paidOut 8640, chargesShare 50000+4320−10000 = 44320, ownIncome 200000, remaining 155680.
- `householdTotals`: income 542000, allocatedIncome 42000, plannedIncome 0, expense 100000+38000+8640+35000 = 181640, plannedExpense 35000, remaining 360360.
- `netCharges` with the charges rent (50/50) and car (100 % H) returns rent `{gross:100000, reimbursed:20000, net:80000}` and car `{gross:38000, reimbursed:22000, net:16000}`. A charge without allocation is not returned.
- `budgetStatus` with the Courses budget 40000 returns `{actual:8640, plannedRemaining:0, over:false}`. A budget of 5000 returns `over:true`.
- `budgetForMonth`: a budget starting `2026-11` is absent in `2026-10`. Of two budgets (from `2026-01` and from `2026-09`), October uses the September one.
- SKIPPED ops are absent from every result.
- [ ] **Step 2: Run** the tests. Expected: FAIL.
- [ ] **Step 3: Implement** per §7.2–7.4. Filter by `monthOf(op.date) === month`.
- [ ] **Step 4: Run** the tests. Expected: PASS.
- [ ] **Step 5: Commit** with `feat(domain): monthly flows, totals, net charges, budgets`.
---
### Task 5: Loan amortization (spec §7.5 + Loan "crédit en cours")
**Files:**
- Create: `src/domain/loan.ts`
- Test: `tests/domain/loan.test.ts`
**Interfaces:**
- Produces:
```ts
export interface LoanInput { principal: Cents; annualRatePct: number; durationMonths: number;
startDate: string; insuranceMonthly: Cents; paymentOverride: Cents | null;
referenceDate: string | null; referenceRemainingCapital: Cents | null; }
export interface ScheduleRow { n: number; date: string; payment: Cents; interest: Cents;
principal: Cents; insurance: Cents; remaining: Cents; beforeTracking: boolean; }
export function monthlyPayment(principal: Cents, annualRatePct: number, months: number): Cents;
export function buildSchedule(l: LoanInput): ScheduleRow[];
export function remainingAt(rows: ScheduleRow[], date: string): Cents;
export function loanSummary(rows: ScheduleRow[], today: string): { payment: Cents; insurance: Cents; endDate: string; remaining: Cents; interestPaid: Cents; interestLeft: Cents; };
```
- `payment` excludes insurance. Row dates are `startDate` + (n−1) months, clamped to the end of the month.
- `remainingAt` returns the remaining capital after the last row whose date is ≤ the given date (or the principal if there is none).
- [ ] **Step 1: Write the failing tests.**
- `monthlyPayment(2000000, 4, 48)` returns `45158`, and `monthlyPayment(1200000, 0, 12)` returns `100000`.
- `buildSchedule({principal:2000000, annualRatePct:4, durationMonths:48, startDate:'2026-01-05', insuranceMonthly:1500, paymentOverride:null, referenceDate:null, referenceRemainingCapital:null})`:
- 48 rows ;
- row 1 is `{date:'2026-01-05', interest:6667, principal:38491, insurance:1500, remaining:1961509}` ;
- the last row has `remaining: 0`, and its principal equals the previous row's remaining (the last payment absorbs the residue) ;
- Σ principal = 2000000.
- Reference mode: same loan with `referenceDate:'2026-06-10'`, `referenceRemainingCapital:1800000`, `paymentOverride:46000`. The rows dated ≤ 2026-06-10 have `beforeTracking:true`. The first row after (`2026-07-05`) has interest `round(1800000*0.04/12)=6000` and principal `40000`. Rows continue until remaining is 0. The final payment is ≤ 46000, and the row count may differ from 48.
- With `startDate` on day 31 (`'2026-01-31'`), row 2's date is `'2026-02-28'`.
- `remainingAt(rows,'2026-01-04')` returns 2000000, and `remainingAt(rows,'2026-01-05')` returns 1961509.
- [ ] **Step 2: Run** the tests. Expected: FAIL.
- [ ] **Step 3: Implement.** Use `interest = Math.round(remaining * rate/100/12)` and `principal = payment − interest`; on the last row (`principal ≥ remaining`), set `principal = remaining` and `payment = principal + interest`.
- In reference mode, the rows before `referenceDate` are computed from the original loan only for display (`beforeTracking:true`). From the first date > `referenceDate`, restart with remaining = `referenceRemainingCapital` and payment = `paymentOverride ?? monthlyPayment(refCapital, rate, durationMonths − rowsBefore)`.
- Guard: if payment ≤ interest, throw `Error('Mensualité insuffisante pour couvrir les intérêts')`.
- [ ] **Step 4: Run** the tests. Expected: PASS.
- [ ] **Step 5: Commit** with `feat(domain): loan amortization schedule`.
---
### Task 6: Recurrence dates and occurrence planning (spec §9, §8)
**Files:**
- Create: `src/domain/recurrence.ts`
- Test: `tests/domain/recurrence.test.ts`
**Interfaces:**
- Consumes: `Split`, `AllocationMode`, `fullSplit`, date helpers.
- Produces:
```ts
export interface RecurringDef { id: string; kind: OpKind; amount: Cents; label: string; categoryId: string;
accountUserId: UserId; split: Split; frequency: 'MONTHLY'|'QUARTERLY'|'YEARLY'; dayOfMonth: number;
startDate: string; endDate: string | null; paused: boolean;
allocatedToRecurringId: string | null; allocationMode: AllocationMode | null; }
export function occurrenceDates(r: RecurringDef, fromMonth: string, toMonth: string): string[];
export function splitForAllocation(mode: AllocationMode, accountUserId: UserId, targetSplit: Split | null, custom: Split, userIds: UserId[]): Split;
export function planOccurrences(recs: RecurringDef[], existingKeys: Set<string>, today: string, userIds: UserId[], horizonMonths?: number): PlannedOccurrence[];
// PlannedOccurrence = Omit<Op,'id'|'status'> & { status: 'PLANNED'; occurrenceDate: string }; key = `${recurringId}|${occurrenceDate}`
```
- Rules:
- The months included are those `m` with `m ≥ monthOf(startDate)` and `(monthsBetween(start, m) % step === 0)`, where step is 1, 3 or 12.
- The day is `min(dayOfMonth, daysInMonth)`.
- Dates must satisfy `startDate ≤ date ≤ endDate` (when `endDate` is set).
- `planOccurrences` covers the months from `monthOf(today)` to `+horizonMonths−1` (default 12), skips paused recurrings and existing keys, and sets the allocation split with `splitForAllocation`.
- An income recurring with no allocation gets `fullSplit(accountUserId)`. An expense gets `r.split`.
- If the allocation target is missing from `recs`, it falls back to `fullSplit(accountUserId)` and keeps the allocation null.
- [ ] **Step 1: Write the failing tests.**
- A monthly recurring on day 31 from `2026-10-31`, over `2026-10`..`2027-03`, gives `['2026-10-31','2026-11-30','2026-12-31','2027-01-31','2027-02-28','2027-03-31']`.
- A quarterly recurring from `2026-11-15` over `2026-10`..`2027-12` gives `['2026-11-15','2027-02-15','2027-05-15','2027-08-15','2027-11-15']`.
- A yearly recurring from `2025-03-01` over `2026-01`..`2027-12` gives `['2026-03-01','2027-03-01']`.
- A recurring with `endDate:'2026-12-15'`, monthly on day 20, over `2026-10`..`2027-02` gives `['2026-10-20','2026-11-20']`.
- `splitForAllocation('REDUCE_SHARED','H',{H:5000,C:5000},{},['H','C'])` returns the 50/50 split, `'BENEFICIARY_ONLY'` returns `{H:10000,C:0}`, and `'CUSTOM'` returns the custom split.
- `planOccurrences` with today `2026-10-27` and a monthly rent from `2024-01-05` gives 12 occurrences, starting at `2026-10-05` (no retroactive months before the current month) and ending at `2027-09-05`.
- With `existingKeys` holding `rent|2026-10-05`, it gives 11 occurrences.
- A paused recurring gives 0.
- An IK income recurring allocated to `car` (REDUCE_SHARED, car split 100 % H) gets the split `{H:10000,C:0}` and `allocatedToRecurringId:'car'`.
- A dangling target gives `allocatedToRecurringId:null` and the full split for the account holder.
- [ ] **Step 2: Run** the tests. Expected: FAIL.
- [ ] **Step 3: Implement.**
- [ ] **Step 4: Run** the tests. Expected: PASS.
- [ ] **Step 5: Commit** with `feat(domain): recurrence dates and occurrence planning`.
---
### Task 7: Auth, first-run setup, login
**Files:**
- Create: `src/server/auth.ts`, `src/server/actions/auth.ts`, `src/middleware.ts`, `src/app/(public)/setup/page.tsx`, `src/app/(public)/login/page.tsx`, `src/app/(public)/layout.tsx`, `scripts/reset-password.ts`
- Test: `tests/server/auth.test.ts`
**Interfaces:**
- Consumes: `prisma`, `parseEuro`, `percentToBp`, `validateSplit`.
- Produces:
- `hashPassword(p: string): Promise<string>` and `verifyPassword(p: string, h: string): Promise<boolean>`, using bcryptjs with cost 10.
- `getSession()`: an iron-session with cookie `hcl_fin`, `secure:false` (LAN HTTP) and `maxAge` 90 days, storing `{userId?: string}`.
- `requireUser(): Promise<User>`: redirects to `/login` if there is no user, and to `/setup` if no users exist.
- `isSetupDone(): Promise<boolean>`.
- Actions:
- `setupAction(formData)` creates both users. Each user's fields are firstName, login, password (≥ 8 chars), confirmation and color.
- It writes `Setting.defaultSplit` from the default split percent for user 1 (user 2 gets the remainder).
- It takes an optional opening balance amount + direction and creates a Settlement dated `todayParis()`.
- It logs in user 1 and redirects to `/`.
- It refuses to run if users already exist.
- `loginAction(formData)` and `logoutAction()`.
- `scripts/reset-password.ts <login> <newPassword>`, run inside the container as `node scripts/reset-password.js` after build. Compile it with tsx in the Dockerfile or ship it via `npx tsx`, whichever works in the standalone image.
- [ ] **Step 1: Write the failing test.** It runs against `TEST_DATABASE_URL`: a `beforeAll` runs `prisma migrate reset --force --skip-seed` with `DATABASE_URL` pointing at the test DB, then truncates. Test `hashPassword`/`verifyPassword` (round-trip true, wrong password false). Test that a `createHousehold({...})` helper (extracted from `setupAction`, pure DB without cookies) creates 2 users, the Setting defaultSplit `{u1:6000,u2:4000}` for an input of 60 %, and a Settlement when the opening balance is `"150"` with direction `u2→u1`. A second call throws `Error('Installation déjà effectuée')`.
- [ ] **Step 2: Run** `npx vitest run tests/server/auth.test.ts`. Expected: FAIL.
- [ ] **Step 3: Implement** the auth helpers and `createHousehold`, then the setup and login pages.
- The pages use a centered white card on the `#f5f6fa` background, with the logo (indigo square "€" + "Finances").
- The setup form has two side-by-side person blocks (stacked on mobile), each with a color picker defaulting to `#4f46e5` / `#db2777`. Below them come the default split (one % input, default 50) and the "Solde d'ouverture (facultatif)" section.
- Errors show as French inline messages.
- `middleware.ts` only redirects unauthenticated requests (no cookie) to `/login`, except `/login`, `/setup` and `/_next`. The pages enforce the full check with `requireUser`.
- [ ] **Step 4: Run** the tests. Expected: PASS. Then run `npm run dev` and check by hand that `/` redirects to `/setup`, that setup redirects to `/`, and that after logout `/login` works.
- [ ] **Step 5: Commit** with `feat: auth, first-run setup, login`.
---
### Task 8: App shell, UI kit, data loading, recurring sync
**Files:**
- Create:
- `src/server/mappers.ts`, `src/server/repo.ts`, `src/server/sync.ts`
- `src/app/(app)/layout.tsx`, `src/components/Sidebar.tsx`, `src/components/MobileNav.tsx`
- `src/components/ui/{Card,Chip,Avatar,Button,MonthSwitcher,Field,Pills,Amount}.tsx`
- Modify: `src/app/globals.css` (Inter font via `next/font/google`, color tokens as CSS variables)
- Test: `tests/server/sync.test.ts`
**Interfaces:**
- Consumes: `planOccurrences`, `toIsoDate`, `fromIsoDate`, `centsFromDecimal`, `requireUser`.
- Produces:
- `mappers.ts`: `toOp(row with splits): Op`, `toRecurringDef(row with splits): RecurringDef`, `toSettlement(row): Settlement`.
- `repo.ts`:
- `getUsers(): Promise<{id, firstName, color}[]>` (order by createdAt) ;
- `getCategories(kind?: OpKind)` ;
- `getOpsForMonth(month: string): Promise<Op[]>` ;
- `getAllActualOps(): Promise<Op[]>` ;
- `getSettlements(): Promise<Settlement[]>` ;
- `getRecurringDefs(): Promise<RecurringDef[]>` ;
- `getDefaultSplit(): Promise<Split>`.
- `sync.ts`: `syncRecurrings(today?: string): Promise<number>` loads the defs and existing keys, then runs `prisma.operation.createMany({skipDuplicates:true})` plus the split rows. It returns the count created. It is called once at the top of `(app)/layout.tsx`.
- UI kit:
- `<Card>`: white, 1px `#e5e7eb` border, radius 14, padding 18.
- `<Chip tone="person|split|planned|link" color?>`
- `<Avatar user>`
- `<Amount cents kind? sign?>`: green for income, red for expense, tabular-nums.
- `<MonthSwitcher month basePath>`: ‹ › links using `?m=YYYY-MM`.
- `<Pills options value onChange>`
- Layout:
- desktop sidebar at 210px as in the mockup, with the items Tableau de bord, Opérations, Récurrents & prévu, Budgets, Crédits & charges, Simulateur (disabled, "bientôt" chip), Réglages, and Déconnexion ;
- on mobile (<768px), a bottom tab bar with Accueil, Opérations, a central **+** button that opens the quick entry, Récurrents and Plus (a menu with the rest).
- [ ] **Step 1: Write the failing test** (`TEST_DATABASE_URL`). Seed 2 users, a category, and a monthly recurring rent from `2026-01-05`. `syncRecurrings('2026-10-27')` returns 12, and a second call returns 0. Then:
- mark the `2026-10-05` occurrence SKIPPED, delete the `2026-11-05` one, and call sync again: it returns 1 (November is recreated, the skipped October is not) ;
- delete the Recurring: the ACTUAL operations that pointed at it still exist with `recurringId` null (Review Focus 4).
- [ ] **Step 2: Run** the tests. Expected: FAIL.
- [ ] **Step 3: Implement** the repo, mappers and sync, then the layout and UI kit. Match the mockup (`dashboard-v2.html`) for the spacing, colors and typography.
- [ ] **Step 4: Run** the tests. Expected: PASS. In `npm run dev`, the shell renders at 1280px and 390px wide without horizontal scroll.
- [ ] **Step 5: Commit** with `feat: app shell, UI kit, data loading, recurring sync`.
---
### Task 9: Quick entry form, operation and settlement actions
**Files:**
- Create: `src/components/OperationForm.tsx`, `src/components/QuickAddButton.tsx`, `src/server/actions/operations.ts`, `src/server/actions/settlements.ts`, `src/components/SettlementDialog.tsx`
- Test: `tests/server/operations.test.ts`
**Interfaces:**
- Consumes: `parseEuro`, `validateSplit`, `splitForAllocation`, `fullSplit`, `getDefaultSplit`, the UI kit.
- Produces:
- `saveOperation(input: OperationInput): Promise<{ok: true} | {ok: false; error: string}>`, where:
```ts
OperationInput = { id?: string; kind: OpKind; amount: string; label: string; categoryId: string; date: string;
accountUserId: string; status: 'PLANNED'|'ACTUAL'; split: Split; note?: string;
allocatedToRecurringId?: string|null; allocatedToOperationId?: string|null; allocationMode?: AllocationMode|null;
makeRecurring?: { frequency: Frequency; endDate: string|null } }
```
- It validates with zod, `parseEuro` and `validateSplit`, and rejects allocation fields on an EXPENSE.
- With `makeRecurring`, it creates a Recurring (dayOfMonth = the day of `date`, startDate = `date`) **and** the operation as its first occurrence, with `recurringId` and `occurrenceDate` set.
- On update, it replaces the splits.
- `deleteOperation(id)`.
- `confirmOperation(id, amount: string, date: string)` sets the status to ACTUAL.
- `skipOperation(id)`: for a recurring occurrence it sets status SKIPPED, otherwise it deletes the operation.
- `saveSettlement({fromUserId,toUserId,amount,date,note})`.
- All of them call `revalidatePath('/', 'layout')`.
- The form's behavior:
- **Defaults**: the type is Dépense, the date is `todayParis()`, the payer is the logged-in user, the split is the household default for an expense and 100 % of the receiver for an income (switching the type or payer recomputes it unless the user picked "Perso…").
- **Split pills**: the household default ("50 / 50" label from the bp), "100 % {prénom1}", "100 % {prénom2}" and "Perso…", which shows one % input per person with a live total.
- **Advanced section** (collapsed "+ Récurrent, prévue, affecter à une charge"):
- a "Prévue" toggle ;
- "Rendre récurrent" (frequency and optional end date) ;
- for an income only, "Affecter à une charge": a select listing the expense recurrings and the expense ops of the last 3 months, plus the mode pills "Réduit la charge pour tous" (REDUCE_SHARED, default), "Profite au bénéficiaire" and "Perso", which prefill the split ;
- a note.
- **Presentation**: on mobile it is a full-screen sheet, on desktop a centered modal. The layout follows the mockup's phone screen (the big amount input uses `inputMode="decimal"`).
- [ ] **Step 1: Write the failing tests** (`TEST_DATABASE_URL`). These cover `saveOperation`:
- The amount `"86,40"` with a 50/50 split is stored as 86.40 with two split rows.
- A split of 3333/3333 returns `{ok:false, error:'La répartition doit totaliser 100 %.'}`.
- The amount `"0"` returns `{ok:false, error:'Montant invalide.'}`.
- An income allocated to an expense op, then deletion of that expense op: the income still exists with `allocatedToOperationId` null (Review Focus 4).
- `makeRecurring` monthly from `2026-10-27` creates 1 Recurring and an op whose `occurrenceDate` is `2026-10-27`. A following `syncRecurrings('2026-10-27')` creates 11 more, not 12.
- `skipOperation` on a recurring occurrence sets SKIPPED, and on a one-off op deletes it.
- `saveSettlement` with from === to returns an error.
- [ ] **Step 2: Run** the tests. Expected: FAIL.
- [ ] **Step 3: Implement** the actions, then the form and the `QuickAddButton` (used in the dashboard header, the mobile **+** tab and the Opérations page).
- [ ] **Step 4: Run** the tests. Expected: PASS. Then in the browser at 390px, enter "86,40 Carrefour" with the payer set to person 2 and a 50/50 split: it saves and shows a success toast.
- [ ] **Step 5: Commit** with `feat: quick entry form and operation/settlement actions`.
---
### Task 10: Dashboard
**Files:**
- Create: `src/app/(app)/page.tsx`, `src/components/dashboard/{HouseholdCards,BalanceBanner,PersonCard,BudgetsCard,NetChargesCard,RecentOps,ToConfirmBadge}.tsx`
- Test: `tests/server/dashboard.test.ts` (data assembly)
**Interfaces:**
- Consumes: `getOpsForMonth`, `getAllActualOps`, `getSettlements`, `getUsers`, `computeBalances`, `describeBalance`, `personFlows`, `householdTotals`, `netCharges`, `budgetStatus`, `budgetForMonth`, `SettlementDialog`.
- Produces: `loadDashboard(month: string, viewerId: string, today: string = todayParis()): Promise<DashboardData>` in `src/server/repo.ts`. `DashboardData` holds:
- `totals` and `persons: {user, flows}[]` ;
- `balance: {text: string; debtor?; creditor?; amount?} | null` and `lastSettlementDate: string|null` ;
- `budgets` (with category name/emoji) and `netCharges` ;
- `recent: Op[]` (the 8 most recent of the month by date desc, PLANNED included) ;
- `toConfirmCount` (PLANNED with date ≤ today, all months).
The balance text is computed from the viewer's point of view:
- viewer is the creditor: `"{débiteur} te doit {montant}"` ;
- viewer is the debtor: `"Tu dois {montant} à {créancier}"` ;
- balanced: `"Vous êtes à l'équilibre"`.
- [ ] **Step 1: Write the failing test.** Insert the Task 4 fixture in the test DB, with users whose firstName is "H" and "C". The balance for H is: rent +50000, employer −10000, groceries paid by C −4320, car loan and IK 0, so H = 35680. Assert:
- `loadDashboard('2026-10', H.id).balance.text === 'C te doit ' + formatEuro(35680)` ;
- `loadDashboard('2026-10', C.id).balance.text === 'Tu dois ' + formatEuro(35680) + ' à H'` ;
- `persons[0].flows.remaining === 239680` ;
- `toConfirmCount === 0` when today is `2026-10-27`, because the planned op is dated 10-30.
- [ ] **Step 2: Run** the test. Expected: FAIL.
- [ ] **Step 3: Implement** `loadDashboard` and the page, laid out as in the mockup:
- header (MonthSwitcher + "+ Nouvelle opération") ;
- 3 household cards (Entrées with "dont X € remboursés par l'employeur", Sorties with "dont X € prévus, pas encore passés", Reste with "après les dépenses prévues") ;
- amber balance banner with the "Enregistrer un remboursement" button (prefilled from debtor to creditor with the amount) and "depuis le dernier remboursement (JJ/MM)" ;
- 2 person cards ;
- budgets and net charges side by side (stacked on mobile) ;
- the recent operations table (PLANNED rows at 65 % opacity with the amber "prévue" chip, the "payé par {prénom}" chip in the person's color, the split chip, and the "↳ {charge}" link chip) ;
- a small amber pill "N à confirmer" linking to `/recurrents`, shown when `toConfirmCount > 0`.
Empty states:
- no budget: "Aucun budget défini" with a link to Budgets ;
- no net charge: hide the card ;
- no operation: "Aucune opération ce mois-ci".
- [ ] **Step 4: Run** the tests. Expected: PASS. Check visually at 1280px and 390px against the mockup.
- [ ] **Step 5: Commit** with `feat: monthly dashboard`.
---
### Task 11: Operations page
**Files:**
- Create: `src/app/(app)/operations/page.tsx`, `src/components/operations/{OpsFilters,OpsTable,EditOperationDialog}.tsx`
- Modify: `src/server/repo.ts` (add `searchOps`)
- Test: `tests/server/search.test.ts`
**Interfaces:**
- Produces: `searchOps(f: {month: string; userId?: string; categoryId?: string; kind?: OpKind; status?: 'PLANNED'|'ACTUAL'; q?: string}): Promise<Op[]>`.
- `userId` matches the account holder **or** anyone with a share > 0.
- `q` is a case-insensitive `contains` on the label.
- SKIPPED ops are always excluded, and results are sorted by date desc.
- [ ] **Step 1: Write the failing test.** On a fixture, filtering by `q:'carre'` finds "Carrefour". `userId:C` finds the rent split 50/50 that H paid. `status:'PLANNED'` returns only planned ops. SKIPPED ops never appear.
- [ ] **Step 2: Run** the test. Expected: FAIL.
- [ ] **Step 3: Implement.**
- The filters are a URL search-params form (MonthSwitcher, person, category, type, status, search).
- The table matches the mockup's table style. On mobile it becomes a list of cards.
- Clicking a row opens `OperationForm` in edit mode with a "Supprimer" button, behind a confirm dialog.
- The month footer totals entries and expenses.
- [ ] **Step 4: Run** the tests. Expected: PASS. Then edit an op's split in the browser and check that the dashboard reflects it.
- [ ] **Step 5: Commit** with `feat: operations list with filters and edit`.
---
### Task 12: Récurrents & prévu
**Files:**
- Create: `src/app/(app)/recurrents/page.tsx`, `src/components/recurrents/{RecurringList,RecurringForm,ToConfirmList,UpcomingList}.tsx`, `src/server/actions/recurrings.ts`
- Test: `tests/server/recurrings.test.ts`
**Interfaces:**
- Produces:
- `saveRecurring(input)`, where the input matches the `Recurring` fields with `amount: string` and `split`, plus the allocation fields for income.
- On update, it deletes the PLANNED occurrences of this recurring with `date ≥ todayParis()`, then runs `syncRecurrings()`.
- Past PLANNED and ACTUAL occurrences stay untouched (§9).
- `setRecurringPaused(id, paused)`: pausing deletes the future PLANNED occurrences, resuming runs sync.
- `endRecurring(id, endDate)`: sets `endDate` and deletes the PLANNED occurrences after it.
- `deleteRecurring(id)`: deletes the future PLANNED occurrences, then the template (ACTUAL history is kept via SetNull).
- Loan-linked recurrings are read-only here, with the hint "Géré depuis Crédits".
- [ ] **Step 1: Write the failing tests.**
- A rent recurring is synced from `2026-10-27`. The 2026-10-05 occurrence is confirmed (ACTUAL). Then `saveRecurring` changes the amount to 105000 with today `2026-10-27`: the 2026-10-05 ACTUAL keeps the old amount, and the occurrences from 2026-11-05 onward have 105000.
- Pausing leaves 0 PLANNED occurrences ≥ today. Resuming brings back 11.
- `endRecurring(id,'2027-01-31')` leaves the last PLANNED occurrence at `2027-01-05`.
- [ ] **Step 2: Run** the tests. Expected: FAIL.
- [ ] **Step 3: Implement.** The page has three sections, in this order:
- **"À confirmer"**: PLANNED with date ≤ today. Each row has an inline amount and date that can be edited, plus "Confirmer" and "Ignorer" buttons.
- **"À venir"**: PLANNED in the next 60 days. This includes one-off planned ops, and has a "+ Dépense prévue" button that opens `OperationForm` with Prévue on.
- **"Modèles récurrents"**: cards showing the label, amount, frequency, next date, payer chip, split chip and allocation chip, with the actions edit / pause / end / delete.
- [ ] **Step 4: Run** the tests. Expected: PASS. Then confirm an occurrence in the browser and check that the dashboard moves it from planned to actual.
- [ ] **Step 5: Commit** with `feat: recurring templates, planned and to-confirm lists`.
---
### Task 13: Budgets
**Files:**
- Create: `src/app/(app)/budgets/page.tsx`, `src/components/budgets/{BudgetEditor,BudgetHistoryChart}.tsx`, `src/server/actions/budgets.ts`
- Test: `tests/server/budgets.test.ts`
**Interfaces:**
- Produces:
- `setBudget(categoryId, amount: string, fromMonth: string)`:
- if a budget for that category exists with `startMonth === fromMonth`, it updates it ;
- otherwise it closes the current one (`endMonth = addMonths(fromMonth,-1)`) and creates a new one from `fromMonth` ;
- an empty amount or `"0"` closes the budget without creating a new one.
- `budgetHistory(categoryId, months: number, untilMonth: string): {month; budget: Cents|null; actual: Cents}[]`.
- [ ] **Step 1: Write the failing tests.** `setBudget(courses,'400','2026-10')` and then `setBudget(courses,'450','2027-01')` give `budgetForMonth` 40000 for `2026-12` and 45000 for `2027-01`. `setBudget(courses,'0','2027-03')` leaves no budget for `2027-03`. `budgetHistory` returns 6 entries in chronological order.
- [ ] **Step 2: Run** the tests. Expected: FAIL.
- [ ] **Step 3: Implement.** The page shows the MonthSwitcher, then one row per expense category with the budget input (saved on blur, "applies from this month"), a progress bar (red if over), "réel / budget" and the planned remaining. Below it, a Recharts bar chart compares budget and actual for the selected category over the last 6 months, in the mockup's colors.
- [ ] **Step 4: Run** the tests. Expected: PASS. Then check in the browser.
- [ ] **Step 5: Commit** with `feat: monthly budgets per category with history`.
---
### Task 14: Crédits & charges
**Files:**
- Create: `src/app/(app)/credits/page.tsx`, `src/app/(app)/credits/[id]/page.tsx`, `src/components/credits/{LoanForm,ScheduleTable,LoanSummaryCards}.tsx`, `src/server/actions/loans.ts`
- Test: `tests/server/loans.test.ts`
**Interfaces:**
- Consumes: `buildSchedule`, `loanSummary`, `syncRecurrings`, `netCharges`.
- Produces:
- `saveLoan(input)`:
- It creates or updates the Loan and its splits.
- It upserts the linked Recurring: EXPENSE, category "Crédit", label = loan name, amount = schedule payment + insurance, dayOfMonth = the startDate day, startDate = first schedule row not `beforeTracking`, endDate = last row date, and accountUserId and split copied from the loan.
- It then deletes the future PLANNED occurrences of that recurring and runs sync.
- `deleteLoan(id)`: the Recurring cascades and ACTUAL history is kept via SetNull.
- [ ] **Step 1: Write the failing tests.** `saveLoan` with the Task 5 loan (20000 €, 4 %, 48 months, start `2026-01-05`, insurance 15 €) and today `2026-10-27`:
- creates a Recurring with amount 46658 (45158+1500) and endDate `2029-12-05` ;
- creates occurrences only from `2026-10-05` (no retroactive ones).
Updating with `referenceDate:'2026-06-10'`, `referenceRemainingCapital:'18000'` and `paymentOverride:'460'` changes the Recurring amount to 47500, and the future PLANNED occurrences follow it.
- [ ] **Step 2: Run** the tests. Expected: FAIL.
- [ ] **Step 3: Implement.**
- **List page**: one card per loan with the name, lender, holder chip, monthly payment incl. insurance, remaining capital today, end date and a progress bar of the % repaid. Below it, the **"Charges affectées"** section shows `netCharges` for the current month (gross − reimbursements = net, as in the mockup).
- **Detail page**: summary cards (mensualité, assurance, capital restant dû, intérêts payés / restants, fin), the affectations this month, and the full schedule table. Rows marked `beforeTracking` are greyed out with the label "avant suivi", and the current row is highlighted.
- **Form fields**: name, lender, capital, rate %, duration in months, first payment date, monthly insurance, holder, split, and the collapsed section "Crédit déjà en cours" (mensualité réelle, capital restant dû au, date).
- [ ] **Step 4: Run** the tests. Expected: PASS. Then in the browser, create the car loan and assign an IK income to it: it shows up in net charges.
- [ ] **Step 5: Commit** with `feat: loans with amortization schedule and net charges`.
---
### Task 15: Settings and CSV export
**Files:**
- Create: `src/app/(app)/reglages/page.tsx`, `src/components/settings/{UsersSettings,DefaultSplitSettings,CategoriesSettings,ExportForm}.tsx`, `src/server/actions/settings.ts`, `src/app/api/export/route.ts`, `src/server/csv.ts`
- Test: `tests/domain/csv.test.ts`
**Interfaces:**
- Produces:
- `updateUser(id,{firstName,color,login})` and `changePassword(id,current,next)`, where `next` must have ≥ 8 chars.
- `setDefaultSplit(split)`.
- `saveCategory({id?,name,emoji,kind})` and `archiveCategory(id, archived)`. Archived categories are hidden from the form pickers but still shown on existing ops.
- `opsToCsv(ops, users, categories): string`:
- UTF-8 with BOM, `;` separator, CRLF line endings ;
- header `Date;Type;Libellé;Catégorie;Montant;Payé par;Statut;Part {prénom1} %;Part {prénom2} %;Affecté à;Note` ;
- dates in JJ/MM/AAAA, amounts like `-86,40` (comma decimal, sign by type), statut `Réel`/`Prévu`, SKIPPED excluded ;
- fields containing `;`, `"` or a newline are quoted and their `"` escaped.
- `GET /api/export?from=YYYY-MM&to=YYYY-MM` (auth required) returns `text/csv` with `Content-Disposition: attachment; filename="finances-{from}_{to}.csv"`.
- [ ] **Step 1: Write the failing test.**
- `opsToCsv` with one expense "Carrefour; Bio" of 8640, 50/50, paid by C, starts with `'Date;Type;'`.
- Its line is `27/10/2026;Dépense;"Carrefour; Bio";Courses;-86,40;C;Réel;50;50;;`.
- A SKIPPED op is absent.
- [ ] **Step 2: Run** the test. Expected: FAIL.
- [ ] **Step 3: Implement** `opsToCsv`, the route and the settings page. The page has four cards: Personnes (prénom, identifiant, couleur, mot de passe), Répartition par défaut, Catégories (list grouped by type with emoji + name inline edit, add, archive toggle) and Export (from/to month pickers + button).
- [ ] **Step 4: Run** `npm test`. Expected: all PASS. Then rename a person in the browser and check that the dashboard uses the new name.
- [ ] **Step 5: Commit** with `feat: settings and CSV export`.
---
### Task 16: Production Docker stack, backups, README
**Files:**
- Create: `Dockerfile`, `docker-compose.yml`, `docker/entrypoint.sh`, `docker/backup.sh`, `README.md`
- Modify: `.env.example` (production vars), `.dockerignore`
**Interfaces:**
- Produces:
- `docker compose up -d --build` serves the app on `:3000`.
- The services `app`, `db` and `backup`.
- Env:
- `MARIADB_ROOT_PASSWORD`, `MARIADB_PASSWORD`, `SESSION_SECRET`, `APP_PORT=3000` ;
- `DATABASE_URL` is assembled in compose as `mysql://finances:${MARIADB_PASSWORD}@db:3306/finances`.
- [ ] **Step 1: Dockerfile.** Use a multi-stage build on `node:24-alpine`:
- deps: `npm ci` ;
- build: `npx prisma generate && npm run build` ;
- runner: copy `.next/standalone`, `.next/static`, `public`, `prisma/`, `node_modules/.prisma` and `node_modules/prisma` (CLI for migrate deploy), plus a tsx-free compiled seed (`npx tsc prisma/seed.ts --outDir dist` or esbuild) and the compiled `scripts/reset-password` ;
- `ENTRYPOINT docker/entrypoint.sh`, which runs `prisma migrate deploy`, then `node dist/seed.js` (idempotent upserts), then `node server.js`.
- The image runs as a non-root user and sets `ENV TZ=Europe/Paris`.
- [ ] **Step 2: Compose.**
- `db`: `mariadb:latest`, with `MARIADB_DATABASE=finances`, `MARIADB_USER=finances`, `MARIADB_PASSWORD` and `MARIADB_ROOT_PASSWORD` ; volume `db_data:/var/lib/mysql` ; healthcheck `healthcheck.sh --connect --innodb_initialized` ; no published ports ; `restart: unless-stopped`.
- `app`: depends on db (healthy), `ports: ["${APP_PORT:-3000}:3000"]`, restart unless-stopped.
- `backup`: `mariadb:latest` running `docker/backup.sh`, mounted read-only, with `./backups:/backups`. The script loops forever:
- sleep until 03:00 Europe/Paris ;
- `mariadb-dump -h db -u root -p$MARIADB_ROOT_PASSWORD --single-transaction finances | gzip > /backups/finances-$(date +%F_%H%M).sql.gz` ;
- `find /backups -name '*.sql.gz' -mtime +30 -delete`.
- It also runs one dump at container start.
- [ ] **Step 3: README** (in French). It covers:
- prerequisites ;
- installation (`git clone git@git.fabout.it:hcloez/hcl-finances-manager.git`, `cp .env.example .env`, generate secrets with `openssl rand -hex 32`, `docker compose up -d --build`, open `http://192.168.1.211:3000`) ;
- updating (`git pull && docker compose up -d --build`) ;
- backups (location, retention, PBS note) ;
- restoring (`gunzip -c backups/X.sql.gz | docker compose exec -T db mariadb -u root -p"$MARIADB_ROOT_PASSWORD" finances`) ;
- resetting a password (`docker compose exec app node dist/reset-password.js <login> <nouveau>`) ;
- local development (dev compose, `npm run dev`, `npm test`).
- [ ] **Step 4: Verify locally.**
- Run `docker compose -p finprod up -d --build` with a temporary `.env` and `APP_PORT=3010`. Expected: all 3 services are up, `curl -s -o /dev/null -w '%{http_code}' localhost:3010/login` prints 200, and `ls backups/` shows one `.sql.gz`.
- Smoke test in the browser: setup → add an expense → dashboard shows it → restart the stack → the data is still there.
- Then run `docker compose -p finprod down -v`.
- [ ] **Step 5: Commit** with `feat: production docker stack with nightly backups and README`.
---
### Task 17: Deploy to 192.168.1.211
This needs SSH access to the VM. If it is not available, stop and give the user the README commands.
- [ ] **Step 1:** Push the branch to `origin` and merge it to `main`, per the finishing-a-development-branch choice.
- [ ] **Step 2:** On the VM, run the README "Installation" steps.
- [ ] **Step 3:** From the workstation, `curl -s -o /dev/null -w '%{http_code}' http://192.168.1.211:3000/login` prints 200. `docker compose ps` on the VM shows the 3 services running and `db` healthy.