release: promote beta to main (invoice deposits + cleanups)

[steilerDev]

Release Summary

Promotes the Invoice Deposits feature to stable, along with a budget-line form unification, regular dependency bumps, and a follow-up refactor closing the architect's tech-debt findings from the deposits review cycle.

Changes

Features

• Invoice deposits (Invoice deposits: schema, CRUD API, and cascade (foundation for invoice deposits feature) #1403, Invoice deposits: detail-page UI (Deposits section, Final payment row, add/edit/delete + state toggles) #1404, Invoice deposits: budget rollup integration (residual under parent status, deposits under their own state) #1405) — partial-payment tracking on a single invoice with a per-deposit state machine (pending → paid → claimed with corrections). Each deposit contributes to budget rollups under its own state; the invoice's residual contributes under the parent's state. Net result: budget overview, budget sources, work-item + household-item budget summaries, and the invoices status breakdown header all show deposit-aware totals.
• Budget-line form unification on invoice pages (Unify budget-line creation form on invoice pages #1402) — invoice detail page reuses the shared BudgetLineForm component for the inline create flow (matches the rest of the project's create paths).

Fixes

• InvoiceStatusBreakdown summary deposit-aware (fix(invoice): make status breakdown summary deposit-aware (#1411) #1412) — the InvoicesPage header cards and Dashboard InvoicePipelineCard now reflect the deposit split (Pending/Paid/Claimed/Quotation totals were previously off when invoices had deposits).

Chores / Refactoring

• Architect recommendations cleanup (chore(deposits): dedupe split helper, extract OverflowMenu, fix silent revert errors #1413) — extracted splitByDeposits() helper to dedupe the proportional-split pattern across four call sites; new shared OverflowMenu component replaces the duplicated inline menu in DepositRow/DepositCard; replaced inline style={{}} with a CSS module class; surfaced API errors from revert handlers with a FormError banner (auto-dismiss 6 s) and modal-level error in the state-confirm dialog.
• Dependency bumps (chore(deps): bump the github-actions group with 2 updates #1397, chore(deps-dev): bump the dev-dependencies group with 6 updates #1398, chore(deps): bump the prod-dependencies group with 5 updates #1399, chore(deps): bump fast-uri from 3.1.0 to 3.1.2 #1400) — GitHub Actions group, dev-dependencies group (eslint, stylelint, typescript-eslint), prod-dependencies group (i18next, react-i18next, react-router-dom, webpack), fast-uri.

Change Inventory

Backend (server/, shared/)

• server/src/db/migrations/0032_invoice_deposits.sql (new)
• server/src/db/schema.ts — invoiceDeposits Drizzle table
• server/src/routes/invoiceDeposits.ts (new) + tests
• server/src/services/invoiceDepositService.ts (new) + tests
• server/src/services/invoiceService.ts + tests — deposit embedding on detail, deposit-aware status breakdown summary, list-endpoint payload optimisation
• server/src/services/budgetOverviewService.ts + tests — step 8 deposit-aware aggregate
• server/src/services/budgetSourceService.ts + tests — claimed/unclaimed/discretionary now deposit-aware
• server/src/services/shared/budgetServiceFactory.ts + tests — getInvoiceAggregates/resolveRelationsBatch deposit-aware
• server/src/services/shared/depositAggregateUtils.ts (new) + tests — splitByDeposits, computeDepositAwareAggregates, computeStatusContribution, aggregateInvoiceStatusBreakdown
• server/src/services/diaryAutoEventService.ts + tests — onDepositStatusChanged
• server/src/errors/AppError.ts — DepositsExceedInvoiceTotalError, InvalidDepositStatusTransitionError, InvalidDepositDateForStatusError
• server/src/app.ts — deposit route registration
• shared/src/types/invoice.ts — InvoiceDeposit, InvoiceDepositStatus, CreateDepositRequest, UpdateDepositRequest, Invoice.deposits/Invoice.finalPaymentAmount
• shared/src/types/budget.ts + shared/src/types/budgetSource.ts — JSDoc clarifying deposit-aware split semantics
• shared/src/types/errors.ts — 3 new error codes

Frontend (client/)

• client/src/components/OverflowMenu/ (new) — shared component (Tsx + CSS + index)
• client/src/lib/invoiceDepositsApi.ts (new) + tests — typed API client for deposits CRUD
• client/src/pages/InvoiceDetailPage/InvoiceDepositsSection.tsx (new) + tests — section with table on desktop/tablet, card list on mobile, add/edit/delete + state-toggle controls, Final-payment row, error surfacing
• client/src/pages/InvoiceDetailPage/InvoiceDepositsSection.module.css (new)
• client/src/pages/InvoiceDetailPage/InvoiceBudgetLinesSection.tsx + CSS + tests — unified to consume the shared BudgetLineForm
• client/src/pages/InvoiceDetailPage/InvoiceDetailPage.tsx + tests — wired in the deposits section
• client/src/i18n/en/budget.json — deposit-related strings + 2 network-error fallbacks
• client/src/i18n/de/budget.json — DE mirror with glossary terms Abschlagszahlung / Schlusszahlung
• client/src/i18n/glossary.json — new terms Deposit, Final payment
• Existing test fixtures updated to include deposits: [] / finalPaymentAmount on Invoice mocks

E2E Tests (e2e/)

• e2e/tests/invoices/invoice-deposits.spec.ts (new) — 11 tests covering deposit lifecycle, Final-payment row, mobile card layout, error banner
• e2e/tests/invoices/invoice-budget-line-create-and-link.spec.ts — covers unified budget-line creation flow
• e2e/pages/InvoiceDetailPage.ts — extended POM (deposit locators, add-from-empty-state, modal cancel/save/delete-confirm/state-confirm by data-testid)

Build / Config / Wiki

• package.json + package-lock.json — dep-bump fan-out; dropped stale webpack: 5.105.0 override that was blocking Docker npm ci after the bumps
• client/package.json, server/package.json, docs/package.json — version bumps
• .github/workflows/ci.yml, .github/workflows/release.yml — github-actions group bump
• wiki/API-Contract.md — deposit endpoints, Invoice shape with deposits/finalPaymentAmount, deposit-aware aggregation explainer, new error codes
• wiki/Schema.md — invoice_deposits table

Manual Validation Checklist

Walk through each item against the beta image (or PR-specific image).

• Add a deposit — open an invoice (any status), click "Add deposit", fill amount + due date, submit. Row appears with Pending badge; Final-payment row shows total − deposit.
• State machine — open the deposit menu (⋮), Mark paid → Mark claimed → Revert to paid → Revert to pending. Each transition updates the badge and dates correctly.
• Sum invariant — try adding a deposit whose amount would push Σ deposits > total. The form shows an error with available headroom.
• Delete a paid/claimed deposit — confirmation modal shows a warning banner explaining the budget contribution will be removed.
• Empty state — invoice with no deposits shows the EmptyState component with "Add deposit" CTA. No Final-payment row.
• Mobile layout — viewport ≤ 767 px: deposits render as cards instead of a table. Final-payment row stays visible. Overflow menu items remain reachable.
• Budget overview reflects splits — add a pending deposit of €200 to a quotation invoice of €1000. The InvoicesPage header summary should now show €800 under Quotation and €200 under Pending (instead of the old €1000 / €0). Budget overview totals and the Dashboard pipeline card should reflect the same split.
• Invoice list rows unchanged — /budget/invoices rows still show the parent invoice's full amount in the amount column (per Invoice deposits: detail-page UI (Deposits section, Final payment row, add/edit/delete + state toggles) #1404 AC-5).
• Revert error feedback — if the server rejects a revert (e.g., manual cURL while UI open), the section shows a transient error banner that auto-dismisses after ~6 s.
• Unified budget-line creation — open an invoice, "Create Budget Line": the form is the shared BudgetLineForm (matches the work-item and household-item create flows).
• Spot-check DE locale — switch UI to German; deposit terms render as "Abschlagszahlung" / "Schlusszahlung" consistently.

Testing

• DockerHub beta image: docker pull steilerdev/cornerstone:beta
• PR-specific image: docker pull steilerdev/cornerstone:pr-<PR-NUMBER> (replace placeholder after PR creation)

[steilerDev]

Detailed Validation Walkthrough

Step-by-step instructions to spot-check each major change against the beta image.

Run the beta image locally

docker pull steilerdev/cornerstone:beta
docker run -p 3000:3000 -v cornerstone-data:/app/data steilerdev/cornerstone:beta

Open http://localhost:3000 and log in.

---

1. Invoice deposits — basic flow

1. Navigate to Budget → Invoices, open any invoice (or create a new quotation invoice for vendor X with amount €1000).
2. Scroll to the Deposits section (between Invoice Details and Budget Lines).
3. Click Add deposit. Enter amount=200, dueDate=<any>. Submit.
4. Verify:
   • The deposit row appears with a Pending badge.
   • The Final payment row at the bottom shows €800 (= total − deposit).
   • The invoice's headline amount stays at €1000 (unchanged).

2. Invoice deposits — state machine

1. From the deposit row's overflow menu (⋮), click Mark paid… → enter today's date → confirm.
2. The badge changes to Paid; a paid-date column shows today's date.
3. From the menu, click Mark claimed… → confirm. Badge → Claimed; claimed-date column appears.
4. From the menu, click Revert to paid (no prompt). Badge → Paid; claimed-date clears.
5. From the menu, click Revert to pending (no prompt). Badge → Pending; both date columns clear.

3. Sum invariant + error feedback

1. With the deposit at €200 (Pending), click Add deposit again. Try amount=900.
2. The form shows an error like "Deposit amount exceeds invoice total. Available headroom: €800".
3. Adjust to amount=800, submit. The second deposit is created; Final payment now €0 (muted style).

4. Delete with warning

1. Open the overflow menu on a paid or claimed deposit, click Delete.
2. Confirmation modal renders with an orange warning banner explaining the budget contribution will be removed.
3. Cancel — deposit stays. Re-open, confirm delete — row disappears and Final-payment updates.

5. Budget overview deposit-aware split (#1405 + #1412)

1. Create a new vendor + invoice with amount=1000, status=quotation.
2. Add a pending deposit of €200 on this invoice.
3. Visit Budget → Invoices — the page header should show:
   • Quotation card: €800 contribution (the residual) + count of 1
   • Pending card: €200 contribution + count of 0 (deposits don't increment counts)
4. Mark the deposit paid → header rebalances: Quotation €800, Paid card €200.
5. Visit Dashboard — the InvoicePipelineCard reflects the same splits.

6. Budget overview — work-item / household-item rollups

1. If invoices in the dataset are itemized to budget lines, open Budget → Overview and verify per-source / per-category aggregates show the per-deposit split (each deposit contributes under its state; residual under the parent's state). Zero-deposit invoices behave identically to v2.5.0 (regression-safe).

7. Mobile layout

1. Set the browser viewport to ≤ 767 px (DevTools mobile preview).
2. Open an invoice with at least one deposit.
3. Deposits render as cards instead of a table. Final-payment row stays visible.
4. The overflow menu (⋮) on a card opens; all actions remain reachable and the 44 px touch targets are usable.

8. Invoice list row regression check

1. Visit Budget → Invoices. Each row's amount column should show the invoice's full amount (e.g., €1000), NOT the residual. This was an explicit AC of Invoice deposits: detail-page UI (Deposits section, Final payment row, add/edit/delete + state toggles) #1404 (list rows unchanged).

9. Empty state

1. Find an invoice with zero deposits (or create one).
2. The Deposits section shows the EmptyState with "Add deposit" CTA.
3. No Final-payment row is rendered.

10. Revert error feedback (#1413)

This is harder to trigger without forcing a server error. If you want to validate:

1. Open an invoice with a paid deposit.
2. Either temporarily stop the server, OR craft an inconsistent state, then click "Revert to pending" from the menu.
3. A transient error banner appears at the section top. It auto-dismisses after ~6 seconds.

11. Budget-line creation form (#1402)

1. Open an invoice → click Create Budget Line.
2. The picker modal opens. Pick a work item or household item, then click "Create Budget Line" in the empty-state.
3. Verify the form is the shared BudgetLineForm — same fields, mode toggle (Direct/Unit), submit button as a single <button type="submit">, consistent with the work-item-create and household-item-create flows.

12. German locale

1. Switch the UI to German (profile / language picker).
2. Verify deposit terms render consistently: Abschlagszahlung (Deposit) and Schlusszahlung (Final payment).
3. New error messages "Netzwerkfehler – Status der Abschlagszahlung konnte nicht zurückgesetzt werden" / "...aktualisiert werden..." appear when applicable.

13. Dark mode

1. Toggle dark mode.
2. Spot-check the Deposits section: status badges, overflow menu, Final-payment row, warning banner — all should pick up dark-mode tokens correctly.

---

Rollback

If a critical issue surfaces after promotion, the standard rollback path is:

1. Revert the merge commit on main via gh pr revert.
2. Re-apply the revert back to beta to keep branches in sync.
3. The DockerHub latest and 1.x tags will rebuild from the reverted state.

The invoice_deposits table is additive only — deletion is not required on rollback. Existing invoices behave identically to v2.5.0 (zero-deposit case is regression-tested).

[github-actions]

🎉 This PR is included in version 2.6.0-beta.6 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 2.6.0-beta.7 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀