FinalFactory/MeterVault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Analysis: one selected period, one set of numbers, on every page
ci / build-test (push) Successful in 2m31s
Details

Browse Source 
The dashboards told several stories at once. Overview asked for full
calendar years, meter detail for a fixed 12-month window that was really
13, Trends for 24 months with an Apply button, and the energy pages for
60. Each page derived "today" from UTC, so the first hours of a local day
belonged to yesterday. A missing tariff, a month nobody measured and a
genuine zero all rendered as 0. And a virtual meter -- the one thing the
spreadsheet leans on hardest -- was excluded from analysis outright:
MeterPeriodService returned null for it and the page offered a flow
diagram instead.

docs/DASHBOARD_ANALYSIS_CHANGE_BRIEF.md is the work order. Every choice it
left open is settled in docs/ANALYSIS_IMPLEMENTATION_NOTE.md as D-01..D-58
plus amendments A-01..A-30; code, tests and release notes cite those ids.

The analysis layer

Core/Analysis holds the pure rules: period presets resolved once in the
instance zone into a local date range and a half-open UTC range, bucket
plans, calendar-unit comparisons, coverage runs with a resolution class,
normalized quantities and units, the totals policy, the virtual formula
parser/validator/evaluator, and the cost calculator. "Now" comes from
TimeProvider; services never read the clock.

Normalization now writes, in the same transaction as consumption and by
diff, per-meter rollups by local day and month plus coverage runs and a
rollup state (AnalysisDataWriter). AnalysisReader answers a request from
those tables -- month rollups for month and year buckets, day rollups
otherwise, at most two partial edge days from consumption -- and
CostReader prices the result month by month. Pages, /api/v1 and the CSV
export read nothing else. The unused continuous aggregates are dropped.

The reader's statement count per request is constant whether it covers one
meter or a thousand. On a synthetic 1,000-meter, ten-year instance the
brief's target request (100 meters, ten years, monthly) takes 374 ms
against a two-second target, and the Overview went from 48,244 SQL
statements per load to 205.

Missing is not zero

Every bucket carries a status -- available, partial, missing, unresolved,
invalid, pending -- derived from coverage, never from the amount, with
provenance and a reason code beside it. A true zero is a number and a bar
on the baseline; an unknown bucket is a gap that says why; a month whose
data only exists monthly says so instead of inventing daily detail; a
scope with no tariff says "not priced" instead of 0. Rows whose interval
closes after now are reported separately rather than counted.

Virtual meters are analysis subjects

A virtual meter stores a canonical definition -- expression over m<id>
references, result kind, unit and cost rule -- validated on save and on
read for syntax, unknown or self references, loops and unit/kind rules.
It is evaluated on read from its sources' rollups over their joint
coverage: a missing source makes the bucket missing, an observed zero is
a valid input, a non-finite result is invalid with its dependency path,
and the page lists each source's contribution. Topology links are
topology only and never rewrite a saved calculation; expression-less
meters from older installs are converted once at startup. The editor has
Sum, Difference and Advanced modes with a live preview.

Totals and the bill

Per energy type the totals policy separates use, grid import, export,
generation and runtime, marks breakdown meters as breakdowns and virtual
meters as views, and never adds across units. The bill follows it: grid
import where there is one, separately priced subsections at their own
price, feed-in only on export meters, standing charges once per scope per
local day, manual costs once on their start day, categories as
non-overlapping covers whose composition reconciles to the bill. The
seeded demo's yearly totals now match the spreadsheet.

Pages and navigation

The period lives in the URL and every page reads the same contract, so a
link, a reload and the browser's Back button keep it. Shared components
carry it: page header with breadcrumbs, period toolbar, theme-aware chart
with an accessible table beside it, metric cards, comparison and
availability states, attention items that each link to the one action
that fixes them. Meter detail leads with an Analysis tab and resolves its
tabs by key; the energy page has Overview, History, Flow and Meters; the
old cost-only Trends page is a general Analysis page over portfolio, type,
category, meter or a meter comparison. Records tabs are paged server-side
instead of showing the latest 200. Everything is English and German,
light and dark, down to 360px.

Some figures change on purpose; docs/RELEASE_NOTES.md lists each one and
what the first start after the update does (it rebuilds all analysis data
before the web server listens). docs/SDD.md and CLAUDE.md describe the
system as it now is.

Tests: 1,733 Core and 746 integration, all green, plus an opt-in
performance suite with a synthetic 1,000-meter generator.
This commit is contained in:
Florian Schmidt
2026-09-20 10:29:13 +02:00
parent c0f52dbb6f
commit 8940ef25c3
384 changed files with 82753 additions and 4518 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/Integration.Tests/Costing/DashboardServicesTests.cs
+246
View File
@@ -0,0 +1,246 @@
using MeterVault.Core.Analysis;
using MeterVault.Core.Analysis.Costing;
using MeterVault.Core.Domain;
using MeterVault.Infrastructure.Analysis;
using MeterVault.Infrastructure.Costing;
using MeterVault.Infrastructure.Dashboard;
using MeterVault.Infrastructure.Import;
using MeterVault.Infrastructure.Options;
using MeterVault.Infrastructure.Persistence;
using Microsoft.EntityFrameworkCore;
using static MeterVault.Integration.Tests.Costing.CostSandbox;
using static MeterVault.Integration.Tests.Reconciliation.ReconciliationSupport;
namespace MeterVault.Integration.Tests.Costing;
/// <summary>
/// The services behind the current pages, rerouted through the analysis reader and the cost engine: the overview's
/// KPIs, breakdown, difference and trend, and the energy page's cost. They keep their
/// signatures and show the corrected bill (D-34 – D-42) on the frozen clock of <see cref="CostSandbox.Now"/>.
/// </summary>
/// <remarks>
/// The overview reads the whole instance, so every test starts from — and leaves — an instance
/// without meters, tariffs or manual costs (like <see cref="SeededBillTests"/>).
/// </remarks>
[Collection("Timescale")]
public sealed class DashboardServicesTests(TimescaleFixture fx) : IAsyncLifetime
{
private const int KostenTotal = 2;
private const int KostenStrom = 4;
public async Task InitializeAsync()
{
await using var db = fx.CreateContext();
await ClearDataAsync(db);
}
public async Task DisposeAsync()
{
await using var db = fx.CreateContext();
await ClearDataAsync(db);
}
[Fact]
public async Task The_seeded_overview_follows_the_bill()
{
// D-44 through the legacy services: "this year" is the sheet's 2026 (the data ends in May), "last year" its 2025,
// the latest month with data is May 2026, and the trend, the breakdown and the energy page all add up to the bill.
await LoadReferenceDataAsync();
var (costs, dashboard) = Services();
var sheet = ReadRows(Costs);
var monthly = OracleByMonth(sheet, dateColumn: 0, valueColumn: KostenTotal, firstDataRow: 1);
var summary = await dashboard.GetSummaryAsync(Now);
Assert.Equal(D(2026, 9, 19), summary.AsOf);
Assert.InRange(summary.Year.Current, 2940.19 - 0.02, 2940.19 + 0.02);
Assert.InRange(summary.Year.Previous, 7907.64 - 0.02, 7907.64 + 0.02);
Assert.True(summary.Year.DeltaPercentApplicable);
Assert.Equal((summary.Year.Current - summary.Year.Previous) / summary.Year.Previous * 100, summary.Year.DeltaPercent, 6);
// September and August 2026 have nothing to price: a zero against a zero, with no percentage.
Assert.Equal((0d, 0d), (summary.Month.Current, summary.Month.Previous));
Assert.False(summary.Month.DeltaPercentApplicable);
Assert.Equal(new LatestMonthWithData(D(2026, 5, 1), LatestPeriodBasis.Both), summary.LatestMonth);
Assert.InRange(summary.LatestMonthCost, monthly[D(2026, 5, 1)] - 0.02, monthly[D(2026, 5, 1)] + 0.02);
// The trend is the bill month by month, manual costs included (A09): each month is the sheet's Kosten.
var trend = await dashboard.GetMonthlyTrendAsync(D(2025, 1, 1), D(2026, 1, 1));
Assert.Equal(12, trend.Count);
AssertReconciles(trend.ToDictionary(p => p.Period, p => p.Cost), monthly, 0.02, "trend", minMatches: 12);
Assert.InRange(trend.Sum(p => p.Cost), 7907.64 - 0.02, 7907.64 + 0.02);
// The breakdown is the bill's composition: Strom (Netz × price), Wasser, Heizung — and nothing else priced.
var breakdown = await dashboard.GetCategoryBreakdownAsync(D(2025, 1, 1), D(2026, 1, 1));
Assert.Equal(["Heizung", "Strom", "Wasser"], breakdown.Select(s => s.Name).Order());
Assert.All(breakdown, s => Assert.Equal(CompositionSliceKind.Category, s.Kind));
Assert.InRange(breakdown.Sum(s => s.Cost), 7907.64 - 0.02, 7907.64 + 0.02);
// The energy page's cost is the type's bill, not every electricity meter summed (A04).
await using var db = fx.CreateContext();
var electricity = await db.EnergyTypes.Where(t => t.Key == "electricity").Select(t => t.Id).FirstAsync();
var strom = await costs.GetEnergyTypeCostAsync(electricity, Midnight(2025, 1, 1), Midnight(2026, 1, 1));
var stromSheet = OracleByMonth(sheet, 0, KostenStrom, 1).Where(m => m.Key.Year == 2025).Sum(m => m.Value);
Assert.Equal(CostStatus.Priced, strom.Status);
Assert.InRange(strom.Cost!.Value, stromSheet - 0.02, stromSheet + 0.02);
Assert.Equal(breakdown.Single(s => s.Name == "Strom").Cost, strom.Cost!.Value, 6);
}
[Fact]
public async Task The_breakdown_is_the_bill_s_composition_and_the_trend_adds_up_to_it()
{
await using var box = new CostSandbox(fx);
var (t1, t2) = (await box.TypeAsync(), await box.TypeAsync());
var a = await box.MonthlyAsync(t1, MeterMode.CumulativeCounter, D(2025, 1, 1), [.. Enumerable.Repeat(100d, 20)]);
await box.MonthlyAsync(t2, MeterMode.CumulativeCounter, D(2025, 1, 1), [.. Enumerable.Repeat(50d, 20)]);
await box.TypePriceAsync(t1, 0.10, D(2025, 1, 1));
await box.TypePriceAsync(t2, 0.20, D(2025, 1, 1));
await box.TariffAsync(TariffScope.Global, null, TariffComponent.BasePrice, 5, "EUR/month", D(2025, 1, 1));
var category = await box.CategoryAsync($"A {Guid.NewGuid():N}", 100, meters: [a]);
await box.ManualCostAsync(D(2026, 3, 10), 7);
var (_, dashboard) = Services();
// This year to now (19 September): a and b for January to August (their data ends on 1 September), the global
// standing charge for every day up to today, and the manual cost once.
var standing = (8 * 5) + (19 * 5 / 30d);
var breakdown = await dashboard.GetCategoryBreakdownAsync(D(2026, 1, 1), D(2026, 10, 19));
Assert.Equal(
[(CompositionSliceKind.Uncategorized, (int?)null, 80 + 7d), (CompositionSliceKind.Category, category, 80d), (CompositionSliceKind.StandingCharge, null, Math.Round(standing, 6))],
breakdown.Select(s => (s.Kind, s.CategoryId, Math.Round(s.Cost, 6))));
Assert.Equal(TariffScope.Global, breakdown[2].StandingCharge!.Scope);
Assert.Equal(string.Empty, breakdown[0].Name);
var summary = await dashboard.GetSummaryAsync(Now);
Assert.Equal(summary.Year.Current, breakdown.Sum(s => s.Cost), 6);
Assert.Equal(12 * 25d, summary.Year.Previous, 6);
// The trend: 2024 lies before both meters' install dates, so the bill of each of its months is a known zero (D-24)
// — a point at 0, not a gap. The months of this year add up to the year.
var trend = await dashboard.GetMonthlyTrendAsync(D(2024, 1, 1), D(2026, 10, 19));
Assert.Equal(D(2024, 1, 1), trend[0].Period);
Assert.Equal(33, trend.Count);
Assert.All(trend.Where(p => p.Period.Year == 2024), p => Assert.Equal(0, p.Cost));
Assert.Equal(25, trend.Single(p => p.Period == D(2025, 1, 1)).Cost, 6);
Assert.Equal(32, trend.Single(p => p.Period == D(2026, 3, 1)).Cost, 6);
Assert.Equal(19 * 5 / 30d, trend[^1].Cost, 6);
Assert.Equal(summary.Year.Current, trend.Where(p => p.Period.Year == 2026).Sum(p => p.Cost), 6);
}
[Fact]
public async Task A_month_nothing_was_measured_in_is_not_a_point_on_the_trend()
{
// A meter without an install date is unknown before its first reading, not zero; its type's standing charge only
// starts with its service. Those months are no points — not the known 0 the engine gives a charge not yet due.
await using var box = new CostSandbox(fx);
var type = await box.TypeAsync();
var meter = await box.MeterAsync(type, MeterMode.CumulativeCounter, "kWh");
await box.ReadingsAsync(
meter, (new DateTimeOffset(2026, 2, 1, 8, 0, 0, TimeSpan.FromHours(1)), 0), (Midnight(2026, 3, 1), 100), (Midnight(2026, 4, 1), 250));
await box.TypePriceAsync(type, 0.10, D(2025, 1, 1));
await box.TariffAsync(TariffScope.EnergyType, type, TariffComponent.BasePrice, 5, "EUR/month", D(2025, 1, 1));
var (_, dashboard) = Services();
var trend = await dashboard.GetMonthlyTrendAsync(D(2025, 6, 1), D(2026, 5, 1));
// February: 100 kWh and the charge from the first data day; March: 150 kWh and the charge; April: the charge alone
// (the service runs on through a reading gap, D-40).
Assert.Equal(
[(D(2026, 2, 1), 15d), (D(2026, 3, 1), 20d), (D(2026, 4, 1), 5d)],
trend.Select(p => (p.Period, Math.Round(p.Cost, 6))));
}
[Fact]
public async Task The_difference_view_compares_the_same_elapsed_part_of_last_year()
{
// 10 kWh a day in 2025, 12 in 2026. This year to 19 September 14:37 is set against 1 January – 19 September 14:37
// of 2025 (D-06), not against whole months or the whole year: 261 days each.
await using var box = new CostSandbox(fx);
var type = await box.TypeAsync();
var meter = await box.MeterAsync(type, MeterMode.CumulativeCounter, "kWh", installedAt: D(2025, 1, 1));
var readings = new List<(DateTimeOffset, double)>();
var register = 0d;
for (var day = D(2025, 1, 1); day < D(2026, 9, 19); day = day.AddDays(1))
{
register += day.Year == 2025 ? 10 : 12;
var next = day.AddDays(1);
readings.Add((Midnight(next.Year, next.Month, next.Day), register));
}
await box.ReadingsAsync(meter, [.. readings]);
await box.TypePriceAsync(type, 0.10, D(2025, 1, 1));
var category = await box.CategoryAsync($"D {Guid.NewGuid():N}", 100, meters: [meter]);
var (_, dashboard) = Services();
var rows = await dashboard.GetCategoryDifferenceAsync(D(2026, 1, 1), D(2025, 1, 1), D(2026, 10, 19));
var row = Assert.Single(rows);
Assert.Equal(category, row.CategoryId);
Assert.Equal(261 * 12 * 0.10, row.Current, 6);
Assert.Equal(261 * 10 * 0.10, row.Previous, 6);
Assert.True(row.DeltaPercentApplicable);
Assert.Equal(20, row.DeltaPercent, 6);
}
[Fact]
public async Task An_energy_type_costs_its_billed_meters_and_a_meter_its_own_rule()
{
// A04: the energy page summed every meter of the type — the grid, the house behind it and a subsection of the
// house. The type's bill is the grid import (D-34); each meter's own cost stays available as a view.
await using var box = new CostSandbox(fx);
var type = await box.TypeAsync();
var grid = await box.MeterAsync(type, MeterMode.CumulativeCounter, "kWh", D(2025, 1, 1), MeterMeta.WithRole("{}", MeterRoles.GridImport));
var house = await box.MeterAsync(type, MeterMode.CumulativeCounter, "kWh", D(2025, 1, 1), MeterMeta.WithRole("{}", MeterRoles.TotalLoad));
var car = await box.MonthlyAsync(type, MeterMode.CumulativeCounter, D(2025, 1, 1), [.. Enumerable.Repeat(50d, 12)]);
var pv = await box.MonthlyAsync(type, MeterMode.GenerationCounter, D(2025, 1, 1), [.. Enumerable.Repeat(250d, 12)]);
await box.MonthlyReadingsAsync(grid, D(2025, 1, 1), [.. Enumerable.Repeat(100d, 12)]);
await box.MonthlyReadingsAsync(house, D(2025, 1, 1), [.. Enumerable.Repeat(300d, 12)]);
await box.LinkAsync(house, car);
await box.TypePriceAsync(type, 0.10, D(2025, 1, 1));
var (costs, _) = Services();
var bill = await costs.GetEnergyTypeCostAsync(type, Midnight(2025, 1, 1), Midnight(2026, 1, 1));
Assert.Equal(1200 * 0.10, bill.Cost!.Value, 6);
var houseCosts = await costs.GetMeterCostsAsync(house, Midnight(2025, 1, 1), Midnight(2026, 1, 1));
Assert.Equal(12, houseCosts.Count);
Assert.All(houseCosts, c => Assert.Equal((300d, 30d), (c.Consumption, Math.Round(c.Cost, 6))));
// A generation meter reports generation, and is not costed.
var generation = await costs.GetMeterCostsAsync(pv, Midnight(2025, 1, 1), Midnight(2026, 1, 1));
Assert.All(generation, c => Assert.Equal((0d, 250d, 0d, QuantityKind.Generation), (c.Consumption, c.Generation, c.Cost, c.Kind)));
}
private (CostService Costs, DashboardService Dashboard) Services()
{
var clock = new FixedTimeProvider(Now);
var costs = new CostService(fx, Options(), clock);
return (costs, new DashboardService(fx, costs, clock));
}
private static Microsoft.Extensions.Options.IOptions<MeterVaultOptions> Options() =>
Microsoft.Extensions.Options.Options.Create(new MeterVaultOptions { TimeZone = BerlinId, Currency = "EUR" });
private async Task LoadReferenceDataAsync()
{
await using var db = fx.CreateContext();
var importer = new ReferenceDataImporter(db, new ImportService(db, Normalization(db)), new CsvImporter());
await importer.LoadAsync(Path.Combine(AppContext.BaseDirectory, "fixtures"));
}
private static async Task ClearDataAsync(MeterVaultDbContext db)
{
await db.MeterLinks.ExecuteDeleteAsync();
await db.Consumption.ExecuteDeleteAsync();
await db.Readings.ExecuteDeleteAsync();
await db.MeterEvents.ExecuteDeleteAsync();
await db.ManualCosts.ExecuteDeleteAsync();
await db.CostCategoryMembers.ExecuteDeleteAsync();
await db.Tariffs.ExecuteDeleteAsync();
await db.Tanks.ExecuteDeleteAsync();
await db.MeterSources.ExecuteDeleteAsync();
await db.Meters.ExecuteDeleteAsync();
await db.ImportBatches.ExecuteDeleteAsync();
}
}