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 definitions, IReadOnlyList available) { if (definitions.Count > 8) { throw new DashboardConfigurationException("A dashboard supports no more than eight gauges."); } var identifiers = new HashSet(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 signals, IEnumerable 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); } }