diff --git a/README.md b/README.md index 5a13ee71..e94e2cf0 100644 --- a/README.md +++ b/README.md @@ -59,10 +59,11 @@ docker run -d \ --name cornerstone \ -p 3000:3000 \ -v cornerstone-data:/app/data \ + -v cornerstone-backups:/backups \ steilerdev/cornerstone:latest ``` -Open `http://localhost:3000` -- the setup wizard will guide you through creating your admin account. See the [full deployment guide](https://steilerDev.github.io/cornerstone/getting-started/docker-setup) for Docker Compose, reverse proxy, and OIDC configuration. +Open `http://localhost:3000` -- the setup wizard will guide you through creating your admin account. See the [full deployment guide](https://steilerDev.github.io/cornerstone/getting-started/docker-setup) for Docker Compose, reverse proxy, OIDC, and [scheduled-backup configuration](https://steilerDev.github.io/cornerstone/guides/backup/). ## Roadmap diff --git a/RELEASE_SUMMARY.md b/RELEASE_SUMMARY.md index b6061315..53abc6fc 100644 --- a/RELEASE_SUMMARY.md +++ b/RELEASE_SUMMARY.md @@ -1,15 +1,20 @@ -# v2.4.2 Release Summary +# v2.5.0 Release Summary -A small bug-fix release that tightens up the Budget and Document workflows introduced in v2.4. No new features, no breaking changes, no migration required -- pull and restart. +A focused release that adds **Backup & Restore**, tightens budget VAT handling, and slims down the Budget Overview page. Migration 0031 backfills `includes_vat` on existing budget lines, runs automatically on first start, and requires no manual intervention. + +## What's New + +- **Backup & Restore** -- Cornerstone now ships with a built-in backup feature that snapshots your entire app data directory (SQLite database + diary photos) into a single `tar.gz` archive. Trigger backups manually from the admin UI, run them on a cron schedule, set a retention limit, and restore from any archive in two clicks. Mount a separate volume to `/backups` (or wherever you point `BACKUP_DIR`) and you're set. See the [Backups guide](https://steilerDev.github.io/cornerstone/guides/backup) for setup, scheduling, and restore steps. (#1386) + +## Improvements + +- **Consistent VAT handling across budget lines** (#1385) -- Direct pricing mode now applies the same VAT multiplier as unit pricing (quantity × unit price), so the **Price includes VAT** checkbox behaves identically regardless of which pricing mode you use. Planned amounts are now always stored as gross internally, which means the Budget Overview, Available Funds row, and printed reports compare every line on a like-for-like basis. The `includes_vat` flag is now `NOT NULL` at the database level (defaults to `true`); migration 0031 backfills any pre-existing `NULL` values. ## Bug Fixes -- **Budget source filter now drives every total on the page.** The "Available Funds" and "Remaining Budget" columns in the Cost Breakdown table -- as well as the Pending, Paid, and Quotation summary cards above the table -- now correctly reflect the active source filter. Previously they always showed unfiltered totals, which made the per-source filter misleading when you only wanted to see the picture for a single source. -- **Document picker shows all documents by default.** The "Hide already-linked documents" checkbox in the document picker now starts unchecked, so every document is immediately visible. You no longer have to clear the filter before you can re-link a document that is already attached elsewhere. -- **Mouse wheel no longer changes numeric fields.** Scrolling the page with your mouse wheel while the cursor sits over an Amount or budget field will not accidentally increment or decrement the value -- a common source of silent edits when scrolling long invoice forms. -- **VAT checkbox round-trips correctly.** The VAT / tax checkbox on invoices now preserves its state when you reopen an invoice for editing. Previously the saved state was not always reflected in the form. -- **Vendor picker no longer clears on blur.** Selecting a vendor in the Add Invoice form and then clicking elsewhere on the page (e.g. into the Amount field) no longer clears the selection. -- **Budget Overview summary cards refresh with the source filter.** The Pending, Paid, and Quotation summary cards on the Budget Overview page now refresh correctly when you toggle the source filter, so the headline numbers always match the rows below them. +- **Budget Overview is now the breakdown** (#1389) -- The Budget Health hero card has been removed from the top of the page. The overview now goes straight from the title bar into the Cost Breakdown Table. The Min / Avg / Max perspective toggle, source-filter, and Available Funds row all live inside the table and remain unchanged. The page is faster, prints cleaner, and removes a layer of summary metrics that mostly duplicated what the breakdown already shows. +- **Source name now prints on the Budget Overview** (#1390) -- Print viewports (around 600-720 px) used to trigger the mobile breakpoint, which collapsed the source attribution badge to just a colored dot -- great on a phone, useless on a printout. Print mode now forces the full source name visible with a border-based color treatment, so the printed report shows the actual source attached to each budget line. +- **Broken docs links on the Budget Overview page** (#1384) -- The "Related Pages" links to Work Items and Household Items pointed to non-existent `/overview` sub-paths and now point to the correct guide indices. ## What to Update @@ -17,8 +22,21 @@ A small bug-fix release that tightens up the Budget and Document workflows intro docker pull steilerdev/cornerstone:latest ``` -Restart your container -- no database migration is required. +Restart your container. Migration 0031 runs automatically on first start. + +If you want to enable the new backup feature, mount a backup volume: + +```bash +docker run -d \ + --name cornerstone \ + -p 3000:3000 \ + -v cornerstone-data:/app/data \ + -v cornerstone-backups:/backups \ + steilerdev/cornerstone:latest +``` + +Optionally set `BACKUP_CADENCE` (e.g., `0 2 * * *` for daily at 2 AM) and `BACKUP_RETENTION` (e.g., `7` to keep a week's worth of archives). --- -_Released: 2026-04-28_ +_Released: 2026-05-03_ diff --git a/docs/src/getting-started/configuration.md b/docs/src/getting-started/configuration.md index 4aca320d..b1422e06 100644 --- a/docs/src/getting-started/configuration.md +++ b/docs/src/getting-started/configuration.md @@ -86,5 +86,6 @@ The document integration is automatically enabled when both `PAPERLESS_URL` and | `PAPERLESS_URL` | -- | Base URL of your Paperless-ngx instance used by the server for API calls (e.g., `http://paperless:8000` in Docker) | | `PAPERLESS_API_TOKEN` | -- | API authentication token from Paperless-ngx | | `PAPERLESS_EXTERNAL_URL` | -- | Browser-facing URL for Paperless-ngx links (e.g., `https://paperless.example.com`). If unset, falls back to `PAPERLESS_URL`. | +| `PAPERLESS_FILTER_TAG` | -- | Optional tag name. When set, only Paperless-ngx documents tagged with this name are visible to Cornerstone. Useful for keeping personal documents private when sharing a Paperless-ngx instance across applications. | For detailed setup instructions, see [Documents Setup](/guides/documents/setup). diff --git a/docs/src/guides/budget/budget-overview.md b/docs/src/guides/budget/budget-overview.md index d031ce11..50b6c33f 100644 --- a/docs/src/guides/budget/budget-overview.md +++ b/docs/src/guides/budget/budget-overview.md @@ -5,36 +5,44 @@ title: Budget Overview # Budget Overview -The budget overview dashboard at **Budget > Overview** gives you a high-level view of your project's financial health. It surfaces totals across financing sources, four different "remaining budget" perspectives, and a cost breakdown grouped by **area hierarchy**. +The budget overview at **Budget > Overview** is a single-page report of your project's costs, grouped by **area hierarchy** rather than by category. It rolls everything up from individual budget lines through work items and household items into a clean, printable view of where your money is going -- and which financing source is funding each line. -## Summary Tiles +## Page Layout -At the top of the overview you see a set of summary tiles -- Total Budget, Total Estimated, Total Invoiced, Total Remaining, and one per financing source. Each tile is **clickable**: clicking a tile selects every matching budget line in the table below, so you can jump straight from a headline number into the underlying lines that drive it. Click the same tile again (or click in empty space) to clear the selection. +The page renders the **Cost Breakdown Table** as its primary view, with a per-source filter, a min / avg / max perspective toggle inside the table, and a built-in **Available Funds** row that summarizes each financing source. -## Remaining Budget Perspectives +If your project has no budget data yet, you see a short empty state inviting you to add work items, household items, or invoices. Once you have a few budget lines, the breakdown takes over the page. -The overview provides four ways to look at how much budget remains, each answering a different question: +## Cost Breakdown by Area -| Perspective | Calculation | What It Tells You | -|------------|-------------|-------------------| -| **vs Min Planned** | Financing - (Estimated x (1 - margin)) | Best-case remaining budget assuming all estimates come in under | -| **vs Max Planned** | Financing - (Estimated x (1 + margin)) | Worst-case remaining budget assuming all estimates come in over | -| **vs Actual Cost** | Financing - Actual costs | Remaining budget based on real invoice amounts where available | -| **vs Actual Paid** | Financing - Paid amounts | Remaining budget based on what has actually been paid out | +The cost breakdown table is grouped by your **area hierarchy** rather than by category. This makes it easy to see what each room, floor, or zone of the project actually costs. -Switch between perspectives to understand your financial position from different angles. Early in a project, the min/max planned views are most useful. As invoices arrive, the actual cost and actual paid views become more meaningful. +- Each **area** is a row. Its totals roll up every descendant area beneath it. +- Clicking a row expands it to show child areas and, at the leaf level, the individual budget lines. +- Nested rows are visually indented so the tree is easy to scan. +- Budget lines whose work item or household item has no area assigned are collected in a dedicated **No Area** bucket at the bottom of the table. -## How Projections Work +Each row displays the projected cost, subsidy payback, and remaining amount for that slice of the project. -The budget overview uses a **blended projection model** that combines estimates and actuals: +### Cost Perspectives -- **Budget lines linked to a paid, pending, or claimed invoice** use the itemized invoice amount (0% margin) -- **Budget lines linked to a quotation** use the itemized amount with a +/- 5% margin -- **Budget lines without an invoice link** use the estimated amount with the confidence margin +A **Min / Avg / Max** segmented control above the table switches the projected-cost calculation between three views: + +| Perspective | What It Tells You | +|------------|-------------------| +| **Min** | Best-case cost assuming all estimates come in under their confidence margin | +| **Avg** | Mid-point cost using the middle of each estimate's confidence range | +| **Max** | Worst-case cost assuming all estimates come in over their confidence margin | + +Switch between perspectives to understand your financial position from different angles. Early in a project, Min and Max bracket your exposure. As invoices arrive and confidence levels rise, the three views converge. -This means your projections automatically become more accurate as your project progresses and estimates are replaced by real invoices. +### How Projections Work -### Confidence Margins +The breakdown uses a **blended projection model** that combines estimates and actuals: + +- **Budget lines linked to a paid, pending, or claimed invoice** use the itemized invoice amount (0% margin) +- **Budget lines linked to a quotation** use the itemized amount with a +/- 5% margin +- **Budget lines without an invoice link** use the planned amount with the confidence margin The margin applied to non-invoiced budget lines depends on the confidence level: @@ -45,16 +53,7 @@ The margin applied to non-invoiced budget lines depends on the confidence level: | Quote | +/- 5% | | Invoice | 0% (actual cost used) | -## Cost Breakdown by Area - -The cost breakdown table is grouped by your **area hierarchy** rather than by category. This makes it easy to see what each room, floor, or zone of the project actually costs. - -- Each **area** is a row. Its totals roll up every descendant area beneath it. -- Clicking a row expands it to show child areas and, at the leaf level, the individual budget lines. -- Nested rows are visually indented so the tree is easy to scan. -- Budget lines whose work item or household item has no area assigned are collected in a dedicated **No Area** bucket at the bottom of the table (previously labeled "Unassigned"). - -Each row displays the estimated total, invoiced total, subsidy reduction, and remaining amount for that slice of the project. +This means projections automatically become more accurate as your project progresses and estimates are replaced by real invoices. ### Source Attribution Badges @@ -79,28 +78,18 @@ This makes it easy to spot which source is most depleted, which one is being sub Click any source detail row inside the **Available Funds** expansion to toggle that source on or off. Deselected sources are dropped from the entire breakdown: -- The summary tiles, projected cost range, every nested area row, and the **Available Funds** and **Remaining Budget** (Cost + Net) totals all recalculate against the visible set in real time as you toggle. +- The projected cost range, every nested area row, and the **Available Funds** and **Remaining Budget** (Cost + Net) totals all recalculate against the visible set in real time as you toggle. - A small "X of N selected" caption appears next to **Available Funds** while a filter is active. - The selection is **persisted in the URL** as `?deselectedSources=,` so you can bookmark a filtered view, share it with your bank or partner, or refresh without losing state. - Press **Escape** while focused on a source row to clear all deselections in one go. - Source detail rows stay visible even when every source is deselected -- the filter is never a dead-end; you can always click your way back in. - When you print a filtered view, deselected source rows are hidden from the printed output so the report only shows the sources you actually have selected. -Filtering happens **server-side** (`GET /api/budget/breakdown?deselectedSources=...`), which means subsidy payback math stays consistent with the visible set: subsidies that no longer have any qualifying budget lines drop out cleanly instead of double-counting. The Pending, Paid, and Quotation summary cards at the top of the page also refresh in step with the filter -- pick the sources you care about and the headline numbers update without leaving the page. - -## Financing Source Summary - -A summary of each financing source shows: - -- Total amount available -- Current depletion (based on actual invoice costs) -- Remaining balance - -For a much deeper view of each source -- including every budget line attached to it, grouped by area and work item, with multi-select and mass-move -- see [Financing Sources](financing-sources). +Filtering happens **server-side** (`GET /api/budget/breakdown?deselectedSources=...`), which means subsidy payback math stays consistent with the visible set: subsidies that no longer have any qualifying budget lines drop out cleanly instead of double-counting. ## Subsidy Impact -Approved and disbursed [subsidies](subsidies) are factored into the overview calculations. The dashboard shows how much each subsidy reduces the total cost for its linked category. Pending and rejected subsidies are excluded from calculations. +Approved and disbursed [subsidies](subsidies) are factored into the breakdown calculations. The Available Funds row shows how much each subsidy reduces the net cost for its linked source. Pending and rejected subsidies are excluded from calculations. ## Printing the Overview @@ -110,6 +99,7 @@ The Budget Overview has dedicated **print styling** so you can hand your bank, a - The app chrome -- sidebar, navigation, floating buttons -- is suppressed in print. - Page margins, title spacing, and nested area group boxes are tuned for A4/Letter output. - Inner item separators keep individual budget lines readable when an area group contains many children. +- Source attribution badges keep their **full source name** on the printed page, with a border-based color treatment so the source is legible even if your printer doesn't preserve background colors. - The browser's own print header/footer is suppressed; pick your target (printer or "Save as PDF") and go. :::tip diff --git a/docs/src/guides/budget/work-item-budgets.md b/docs/src/guides/budget/work-item-budgets.md index ab290f0a..f643d6a8 100644 --- a/docs/src/guides/budget/work-item-budgets.md +++ b/docs/src/guides/budget/work-item-budgets.md @@ -44,3 +44,11 @@ See [Invoices & Vendors](vendors-and-invoices) for details on managing invoices A single work item can have multiple budget lines. For example, "Renovate bathroom" might have separate budget lines for plumbing, electrical, and tiling -- each in a different category and potentially funded by different financing sources. +## VAT Handling + +The budget line form has a **Price includes VAT** checkbox. When entering an amount that already includes VAT (gross), leave the box checked; when entering a net amount, uncheck the box and Cornerstone will apply the VAT multiplier on save. + +Internally, planned amounts are always stored as gross (VAT-inclusive). The checkbox controls how Cornerstone interprets your input, not how the value is stored -- so all comparisons in the [Budget Overview](budget-overview), Available Funds row, and printed reports are like-for-like across budget lines, regardless of the pricing mode you chose when entering each one. The same behavior applies whether you use direct pricing or unit pricing (quantity × unit price) on the budget line. + + +