AutoForge/src/AutoForge.Application/Features/Vehicles/Telemetry/LiveDashboard/DashboardGaugeProjection.cs

167 lines
8.3 KiB
C#

using System.Globalization;
using System.Text.Json;
using AutoForge.Diagnostics;
namespace AutoForge.Application.Features.Vehicles.Telemetry.LiveDashboard;
public static class DashboardGaugeProjection
{
public static void ValidateDefinitions(
IReadOnlyList<DashboardGaugeDefinition> definitions,
IReadOnlyList<DashboardSignalBinding> available)
{
if (definitions.Count > 8)
{
throw new DashboardConfigurationException("A dashboard supports no more than eight gauges.");
}
var identifiers = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
foreach (var definition in definitions)
{
if (definition is null)
{
throw new DashboardConfigurationException("Dashboard gauge definitions cannot contain null.");
}
if (string.IsNullOrWhiteSpace(definition.GaugeIdentifier) ||
!StringComparer.Ordinal.Equals(definition.GaugeIdentifier, definition.GaugeIdentifier.Trim()) ||
!identifiers.Add(definition.GaugeIdentifier))
{
throw new DashboardConfigurationException("Gauge identifiers must be nonblank, trimmed and unique ignoring case.");
}
if (string.IsNullOrWhiteSpace(definition.Label) ||
!StringComparer.Ordinal.Equals(definition.Label, definition.Label.Trim()))
{
throw new DashboardConfigurationException("Gauge labels must be nonblank and contain no surrounding whitespace.");
}
if (!Enum.IsDefined(definition.Kind))
{
throw new DashboardConfigurationException("The selected gauge kind is undefined.");
}
if (string.IsNullOrWhiteSpace(definition.ModuleIdentifier) ||
string.IsNullOrWhiteSpace(definition.SignalIdentifier) ||
string.IsNullOrWhiteSpace(definition.Unit))
{
throw new DashboardConfigurationException("Gauge module, signal and unit bindings must be explicit.");
}
if (!double.IsFinite(definition.Minimum) || !double.IsFinite(definition.Maximum) ||
!double.IsFinite(definition.Maximum - definition.Minimum) || definition.Maximum <= definition.Minimum)
{
throw new DashboardConfigurationException("Gauge range must have finite minimum, maximum and positive finite span.");
}
if (definition.DecimalPrecision is < 0 or > 3)
{
throw new DashboardConfigurationException("Gauge decimal precision must be an integer from 0 through 3.");
}
var binding = available.FirstOrDefault(item =>
StringComparer.OrdinalIgnoreCase.Equals(item.ModuleIdentifier, definition.ModuleIdentifier) &&
StringComparer.Ordinal.Equals(item.SignalIdentifier, definition.SignalIdentifier));
if (binding is null)
{
throw new DashboardConfigurationException(
$"Signal '{definition.SignalIdentifier}' on module '{definition.ModuleIdentifier}' has not been observed in a validated positive source snapshot.");
}
if (!StringComparer.Ordinal.Equals(definition.Unit, binding.Unit))
{
throw new DashboardConfigurationException(
$"Gauge unit '{definition.Unit}' does not exactly match source unit '{binding.Unit}'; display conversion does not change binding.");
}
}
}
internal static void ValidateBindings(IEnumerable<DiagnosticSignal> signals, IEnumerable<DashboardSignalBinding> known)
{
foreach (var signal in signals)
{
var previous = known.FirstOrDefault(binding =>
StringComparer.OrdinalIgnoreCase.Equals(binding.ModuleIdentifier, signal.ModuleIdentifier) &&
StringComparer.Ordinal.Equals(binding.SignalIdentifier, signal.SignalIdentifier));
if (previous is not null &&
(!StringComparer.Ordinal.Equals(previous.Unit, signal.Unit) ||
!StringComparer.Ordinal.Equals(previous.Origin, signal.Origin)))
{
throw new InvalidOperationException(
$"Signal '{signal.SignalIdentifier}' on '{signal.ModuleIdentifier}' changed its verified unit or origin.");
}
}
}
internal static DashboardGaugeValue Project(
DashboardGaugeDefinition definition,
DiagnosticSignal? signal,
DiagnosticSignal? lastGood,
DashboardModuleStatus? module,
string? terminalError = null,
string? missingReason = null)
{
if (terminalError is not null)
{
return LastOrError(definition, lastGood, terminalError);
}
if (module is { Outcome: not DiagnosticOutcome.PositiveResponse })
{
return LastOrError(definition, lastGood, module.Error ?? $"Source read outcome: {module.Outcome}.");
}
if (signal is null)
{
return LastOrError(definition, lastGood,
missingReason ?? "The previously bound signal is missing from the latest source response.", DashboardReadingState.Unavailable);
}
if (signal.Quality == SignalQuality.Unknown || !TryGetFiniteNumber(signal, out var value))
{
return new DashboardGaugeValue(definition, DashboardReadingState.Unknown, "--", null, null,
signal.Quality == SignalQuality.Unknown
? "The source quality is Unknown."
: "The source value is null, non-numeric or non-finite.", signal);
}
if (signal.Quality == SignalQuality.Uncertain)
{
return CreateValue(definition, DashboardReadingState.Uncertain, value, signal,
"The source marked this finite value Uncertain.", GetRangeState(value, definition));
}
if (signal.Quality != SignalQuality.Good)
{
return new DashboardGaugeValue(definition, DashboardReadingState.Unknown, "--", null, null,
"The source quality is undefined.", signal);
}
return CreateValue(definition, GetRangeState(value, definition), value, signal, null);
}
internal static DashboardGaugeValue LastOrError(
DashboardGaugeDefinition definition, DiagnosticSignal? last, string error,
DashboardReadingState missingState = DashboardReadingState.Error)
{
if (last is not null && TryGetFiniteNumber(last, out var value))
{
return CreateValue(definition, DashboardReadingState.Stale, value, last,
$"{error} Retaining last-known sample from logical tick {last.LogicalTimeTicks}.",
GetRangeState(value, definition));
}
return new DashboardGaugeValue(definition, missingState, "--", null, null, error, null);
}
internal static DashboardGaugeValue CreateValue(
DashboardGaugeDefinition definition, DashboardReadingState state, double value,
DiagnosticSignal signal, string? reason, DashboardReadingState? rangeState = null)
{
var outOfRangeState = rangeState ?? (state is DashboardReadingState.OutOfRangeLow or DashboardReadingState.OutOfRangeHigh ? state : null);
var displayState = state is DashboardReadingState.OutOfRangeLow or DashboardReadingState.OutOfRangeHigh
? DashboardReadingState.Good : state;
var barPercent = Math.Clamp((value - definition.Minimum) / (definition.Maximum - definition.Minimum) * 100, 0, 100);
return new DashboardGaugeValue(definition, displayState,
value.ToString($"F{definition.DecimalPrecision}", CultureInfo.InvariantCulture),
value, barPercent, reason, signal, outOfRangeState);
}
internal static DashboardReadingState GetRangeState(double value, DashboardGaugeDefinition definition) =>
value < definition.Minimum ? DashboardReadingState.OutOfRangeLow :
value > definition.Maximum ? DashboardReadingState.OutOfRangeHigh : DashboardReadingState.Good;
internal static bool TryGetFiniteNumber(DiagnosticSignal signal, out double value)
{
value = default;
return signal.Value.ValueKind == JsonValueKind.Number &&
signal.Value.TryGetDouble(out value) && double.IsFinite(value);
}
}