Analysis: one selected period, one set of numbers, on every page
ci / build-test (push) Successful in 2m31s
ci / build-test (push) Successful in 2m31s
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
@@ -0,0 +1,292 @@
|
||||
using MeterVault.App.Analysis;
|
||||
using MeterVault.App.MeterEditing;
|
||||
using MeterVault.Core.Analysis;
|
||||
using MeterVault.Core.Analysis.Virtual;
|
||||
using MeterVault.Core.Domain;
|
||||
using MeterVault.Core.Normalization;
|
||||
using MeterVault.Infrastructure.Analysis;
|
||||
using MeterVault.Infrastructure.Normalization;
|
||||
using MeterVault.Infrastructure.Options;
|
||||
using MeterVault.Infrastructure.Persistence;
|
||||
using Microsoft.EntityFrameworkCore;
|
||||
|
||||
namespace MeterVault.Integration.Tests.Editor;
|
||||
|
||||
/// <summary>
|
||||
/// The meter editor's live preview (D-31): an unsaved calculation evaluated through the shared reader over the stored
|
||||
/// sources, with nothing written. The brief's worked example (§5.4): A = 100/80 and B = 150/120 kWh give A+B = 250/200
|
||||
/// and A−B = −50/−40, and a source month that is missing makes the result's month incomplete rather than a number.
|
||||
/// </summary>
|
||||
[Collection("Timescale")]
|
||||
public sealed class MeterDraftPreviewTests(TimescaleFixture fx) : IAsyncLifetime
|
||||
{
|
||||
private const string BerlinId = "Europe/Berlin";
|
||||
|
||||
private static readonly TimeZoneInfo Berlin = TimeZoneInfo.FindSystemTimeZoneById(BerlinId);
|
||||
|
||||
/// <summary>The frozen "now" of every preview here (D-01).</summary>
|
||||
private static readonly DateTimeOffset Now = new DateTimeOffset(2026, 9, 19, 14, 37, 0, TimeSpan.FromHours(2)).ToUniversalTime();
|
||||
|
||||
private readonly List<int> _meters = [];
|
||||
private readonly List<short> _types = [];
|
||||
|
||||
public Task InitializeAsync() => Task.CompletedTask;
|
||||
|
||||
public async Task DisposeAsync()
|
||||
{
|
||||
await using var db = fx.CreateContext();
|
||||
var ids = _meters.ToArray();
|
||||
await db.Consumption.Where(c => ids.Contains(c.MeterId)).ExecuteDeleteAsync();
|
||||
await db.Readings.Where(r => ids.Contains(r.MeterId)).ExecuteDeleteAsync();
|
||||
await db.MeterLinks.Where(l => ids.Contains(l.FromMeterId) || ids.Contains(l.ToMeterId)).ExecuteDeleteAsync();
|
||||
await db.Meters.Where(m => ids.Contains(m.Id)).ExecuteDeleteAsync();
|
||||
var types = _types.ToArray();
|
||||
await db.EnergyTypes.Where(t => types.Contains(t.Id)).ExecuteDeleteAsync();
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task An_unsaved_sum_previews_the_worked_example_without_storing_anything()
|
||||
{
|
||||
var type = await TypeAsync();
|
||||
var a = await GenerationAsync(type, 100, 80);
|
||||
var b = await GenerationAsync(type, 150, 120);
|
||||
var analysis = Analysis();
|
||||
var catalog = await analysis.LoadCatalogAsync();
|
||||
|
||||
// A new meter: Sum mode picks A and B; nothing is declared, so the kind and unit come from the sources (A-08).
|
||||
var draft = new MeterDraft(0, "A + B", type, MeterMode.Virtual, "kWh") { Definition = new VirtualDefinition($"m{a} + m{b}") };
|
||||
var validation = MeterDraftAnalysis.Validate(catalog, draft);
|
||||
Assert.True(validation.IsSavable);
|
||||
var effective = validation.EffectiveDefinition!;
|
||||
Assert.Equal(QuantityKind.Generation, effective.ResultKind);
|
||||
Assert.Equal(VirtualCostRule.None, effective.CostRule); // a generation sum is not costed by default (A-15)
|
||||
|
||||
var result = await analysis.PreviewAsync(MeterDraftAnalysis.Overlay(catalog, draft, effective), draft, JanFeb());
|
||||
|
||||
var series = result.SeriesFor(MeterDraft.NewMeterId)!;
|
||||
Assert.Equal(SeriesBasis.Virtual, series.Basis);
|
||||
Assert.Equal(QuantityKind.Generation, series.Kind);
|
||||
Assert.Equal("kWh", series.Unit);
|
||||
AssertValues(series.Values, 250, 200);
|
||||
AssertAvailable(series.Total, 450);
|
||||
Assert.True(series.IsAdditive);
|
||||
|
||||
// Each source's own values, as the preview table shows them beside the result.
|
||||
var sources = series.Contributions.ToDictionary(c => c.MeterId);
|
||||
AssertValues(sources[a].Values, 100, 80);
|
||||
AssertValues(sources[b].Values, 150, 120);
|
||||
|
||||
// Nothing was written: no meter, no link, no definition.
|
||||
await using var db = fx.CreateContext();
|
||||
Assert.False(await db.Meters.AnyAsync(m => m.EnergyTypeId == type && m.Mode == MeterMode.Virtual));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task An_unsaved_difference_stays_negative_and_an_edited_meter_previews_its_draft()
|
||||
{
|
||||
var type = await TypeAsync();
|
||||
var a = await GenerationAsync(type, 100, 80);
|
||||
var b = await GenerationAsync(type, 150, 120);
|
||||
var existing = await VirtualAsync(type, $"m{a} + m{b}");
|
||||
var analysis = Analysis();
|
||||
var catalog = await analysis.LoadCatalogAsync();
|
||||
|
||||
// Editing the stored sum into a difference: the preview shows the draft, not what is stored.
|
||||
var draft = new MeterDraft(existing, "A − B", type, MeterMode.Virtual, "kWh") { Definition = new VirtualDefinition($"m{a} - m{b}") };
|
||||
var effective = MeterDraftAnalysis.Validate(catalog, draft).EffectiveDefinition!;
|
||||
Assert.Equal(VirtualCostRule.None, effective.CostRule);
|
||||
|
||||
var result = await analysis.PreviewAsync(MeterDraftAnalysis.Overlay(catalog, draft, effective), draft, JanFeb());
|
||||
|
||||
var series = result.SeriesFor(existing)!;
|
||||
AssertValues(series.Values, -50, -40);
|
||||
AssertAvailable(series.Total, -90);
|
||||
Assert.Equal(-1d, series.Contributions.Single(c => c.MeterId == b).Coefficient);
|
||||
|
||||
// The stored definition is still the sum.
|
||||
var stored = await analysis.PreviewAsync(catalog, draft, JanFeb());
|
||||
AssertValues(stored.SeriesFor(existing)!.Values, 250, 200);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task A_missing_source_month_makes_the_preview_month_incomplete_not_a_number()
|
||||
{
|
||||
var type = await TypeAsync();
|
||||
var a = await GenerationAsync(type, 100, 80);
|
||||
var b = await GenerationAsync(type, 150); // B has January only
|
||||
var analysis = Analysis();
|
||||
var catalog = await analysis.LoadCatalogAsync();
|
||||
var draft = new MeterDraft(0, "A + B", type, MeterMode.Virtual, "kWh") { Definition = new VirtualDefinition($"m{a} + m{b}") };
|
||||
var effective = MeterDraftAnalysis.Validate(catalog, draft).EffectiveDefinition!;
|
||||
|
||||
var series = (await analysis.PreviewAsync(MeterDraftAnalysis.Overlay(catalog, draft, effective), draft, JanFeb()))
|
||||
.SeriesFor(MeterDraft.NewMeterId)!;
|
||||
|
||||
AssertAvailable(series.Values[0], 250);
|
||||
Assert.NotEqual(BucketStatus.Available, series.Values[1].Status);
|
||||
Assert.NotEqual(80, series.Values[1].Value);
|
||||
Assert.NotEqual(BucketStatus.Available, series.Total.Status);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task A_draft_that_reads_a_calculation_reading_it_is_a_named_loop()
|
||||
{
|
||||
var type = await TypeAsync();
|
||||
var a = await GenerationAsync(type, 100, 80);
|
||||
var first = await VirtualAsync(type, $"m{a}");
|
||||
var second = await VirtualAsync(type, $"m{first}");
|
||||
var catalog = await Analysis().LoadCatalogAsync();
|
||||
|
||||
var draft = new MeterDraft(first, "First", type, MeterMode.Virtual, "kWh") { Definition = new VirtualDefinition($"m{second} + m{a}") };
|
||||
var validation = MeterDraftAnalysis.Validate(catalog, draft);
|
||||
|
||||
Assert.False(validation.IsValid);
|
||||
var cycle = Assert.Single(validation.Problems, p => p.Kind == VirtualProblemKind.DependencyCycle);
|
||||
Assert.Equal([first, second, first], cycle.MeterIds);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task The_preview_opens_on_the_page_period_and_reaches_history_older_than_24_months()
|
||||
{
|
||||
// Brief §5.1 / D-31: "a preview for the selected historical period" — the page's period carries into the editor,
|
||||
// and all available history spans the sources' data however old it is (here 2022, beyond every relative preset).
|
||||
var type = await TypeAsync();
|
||||
var a = await GenerationAsync(type, new DateOnly(2022, 1, 1), 100, 80);
|
||||
var b = await GenerationAsync(type, new DateOnly(2022, 1, 1), 150, 120);
|
||||
var analysis = Analysis();
|
||||
var catalog = await analysis.LoadCatalogAsync();
|
||||
var draft = new MeterDraft(0, "A + B", type, MeterMode.Virtual, "kWh") { Definition = new VirtualDefinition($"m{a} + m{b}") };
|
||||
var effective = MeterDraftAnalysis.Validate(catalog, draft).EffectiveDefinition!;
|
||||
draft = draft with { Definition = effective };
|
||||
var overlay = MeterDraftAnalysis.Overlay(catalog, draft, effective);
|
||||
|
||||
// Without a page period the preview opens on the last 12 months — where these sources have nothing.
|
||||
Assert.Equal(PeriodPreset.Last12Months, VirtualPreviewPeriod.Initial(null).Period);
|
||||
|
||||
// Opened from /meters/..?from=2022-01-01&to=2022-02-28 it shows exactly that range.
|
||||
var page = AnalysisQuery.Parse("?from=2022-01-01&to=2022-02-28&bucket=day&compare=none", AnalysisDefaults.History);
|
||||
var initial = VirtualPreviewPeriod.Initial(page);
|
||||
Assert.True(initial.IsCustom);
|
||||
var period = await VirtualPreviewPeriod.ResolveAsync(analysis, overlay, draft, initial, Now);
|
||||
Assert.Equal(new DateOnly(2022, 1, 1), period.FirstDay);
|
||||
var result = await analysis.PreviewAsync(overlay, draft, period);
|
||||
AssertValues(result.SeriesFor(MeterDraft.NewMeterId)!.Values, 250, 200);
|
||||
|
||||
// All available history: the sources' own dates, and their values.
|
||||
var all = await VirtualPreviewPeriod.ResolveAsync(analysis, overlay, draft, initial.WithPeriod(PeriodPreset.AllHistory), Now);
|
||||
Assert.Equal(new DateOnly(2022, 1, 1), all.FirstDay);
|
||||
var whole = await analysis.PreviewAsync(overlay, draft, all);
|
||||
AssertAvailable(whole.SeriesFor(MeterDraft.NewMeterId)!.Total, 450);
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------------------------------------ helpers
|
||||
|
||||
private MeterDraftAnalysis Analysis()
|
||||
{
|
||||
var options = Microsoft.Extensions.Options.Options.Create(new MeterVaultOptions { TimeZone = BerlinId });
|
||||
return new MeterDraftAnalysis(new AnalysisReader(fx, options), fx);
|
||||
}
|
||||
|
||||
private static ResolvedPeriod JanFeb() =>
|
||||
PeriodResolver.Resolve(PeriodPreset.Custom, new DateOnly(2026, 1, 1), new DateOnly(2026, 2, 28), Now, Berlin);
|
||||
|
||||
private static void AssertAvailable(BucketValue value, double expected)
|
||||
{
|
||||
Assert.Equal(BucketStatus.Available, value.Status);
|
||||
Assert.Equal(expected, value.Value!.Value, 9);
|
||||
}
|
||||
|
||||
private static void AssertValues(IReadOnlyList<BucketValue> values, params double[] expected)
|
||||
{
|
||||
Assert.Equal(expected.Length, values.Count);
|
||||
for (var i = 0; i < expected.Length; i++)
|
||||
{
|
||||
AssertAvailable(values[i], expected[i]);
|
||||
}
|
||||
}
|
||||
|
||||
private async Task<short> TypeAsync()
|
||||
{
|
||||
await using var db = fx.CreateContext();
|
||||
var type = new EnergyType
|
||||
{
|
||||
Key = $"editor-{Guid.NewGuid():N}",
|
||||
DisplayName = "Editor test",
|
||||
BaseUnit = "kWh",
|
||||
DefaultMode = MeterMode.GenerationCounter,
|
||||
};
|
||||
db.EnergyTypes.Add(type);
|
||||
await db.SaveChangesAsync();
|
||||
_types.Add(type.Id);
|
||||
return type.Id;
|
||||
}
|
||||
|
||||
private async Task<int> MeterAsync(short type, MeterMode mode, string meta = "{}", DateOnly? installedAt = null)
|
||||
{
|
||||
await using var db = fx.CreateContext();
|
||||
var meter = new Meter
|
||||
{
|
||||
Name = $"editor-{Guid.NewGuid():N}",
|
||||
EnergyTypeId = type,
|
||||
Mode = mode,
|
||||
Unit = "kWh",
|
||||
InstalledAt = installedAt,
|
||||
Meta = meta,
|
||||
};
|
||||
db.Meters.Add(meter);
|
||||
await db.SaveChangesAsync();
|
||||
_meters.Add(meter.Id);
|
||||
return meter.Id;
|
||||
}
|
||||
|
||||
/// <summary>A generation counter installed on 1 January 2026 whose months book the given amounts (read on the 1st after each).</summary>
|
||||
private Task<int> GenerationAsync(short type, params double[] months) => GenerationAsync(type, new DateOnly(2026, 1, 1), months);
|
||||
|
||||
/// <summary>A generation counter installed on <paramref name="first"/> (a 1st) whose months book the given amounts.</summary>
|
||||
private async Task<int> GenerationAsync(short type, DateOnly first, params double[] months)
|
||||
{
|
||||
var meter = await MeterAsync(type, MeterMode.GenerationCounter, installedAt: first);
|
||||
var register = 0d;
|
||||
await using (var db = fx.CreateContext())
|
||||
{
|
||||
for (var i = 0; i < months.Length; i++)
|
||||
{
|
||||
register += months[i];
|
||||
db.Readings.Add(new Reading
|
||||
{
|
||||
MeterId = meter,
|
||||
Time = GapAttribution.LocalMidnight(first.AddMonths(i + 1), Berlin).ToUniversalTime(),
|
||||
Value = register,
|
||||
Quality = ReadingQuality.Manual,
|
||||
});
|
||||
}
|
||||
|
||||
await db.SaveChangesAsync();
|
||||
}
|
||||
|
||||
await RecomputeAsync(meter);
|
||||
return meter;
|
||||
}
|
||||
|
||||
private async Task<int> VirtualAsync(short type, string expression)
|
||||
{
|
||||
var meta = VirtualDefinitionJson.Write("{}", new VirtualDefinition(expression, QuantityKind.Generation, "kWh", VirtualCostRule.None));
|
||||
var meter = await MeterAsync(type, MeterMode.Virtual, meta);
|
||||
await RecomputeAsync(meter);
|
||||
return meter;
|
||||
}
|
||||
|
||||
private async Task RecomputeAsync(int meterId)
|
||||
{
|
||||
await using var db = fx.CreateContext();
|
||||
await using var tx = await db.Database.BeginTransactionAsync();
|
||||
var normalization = new NormalizationService(
|
||||
db,
|
||||
NormalizationEngine.CreateDefault(),
|
||||
Microsoft.Extensions.Options.Options.Create(new MeterVaultOptions { TimeZone = BerlinId }),
|
||||
new FixedTimeProvider(Now));
|
||||
await normalization.RecomputeMeterAsync(meterId, null);
|
||||
await db.SaveChangesAsync();
|
||||
await tx.CommitAsync();
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user