Denso/srcs/RobotNet10/Shared/RobotNet10.NavigationTune.Shared/Models/TuningAdvisorModels.cs

namespace RobotNet10.NavigationTune.Shared.Models;

/// <summary>
/// Priority level for tuning suggestions.
/// </summary>
public enum SuggestionPriority
{
    Low = 0,
    Medium = 1,
    High = 2,
    Critical = 3
}

/// <summary>
/// Category of the diagnostic pattern detected from telemetry analysis.
/// </summary>
public enum DiagnosticCategory
{
    Oscillation,
    LargeCTE,
    CornerCutting,
    GoalOvershoot,
    SluggishResponse,
    JerkyMotion,
    VelocityEstimation,
    GoalHeadingError,
    PathEfficiency
}

/// <summary>
/// A detected behavioral pattern from telemetry analysis.
/// </summary>
public class DiagnosticPattern
{
    public DiagnosticCategory Category { get; set; }

    /// <summary>Human-readable description of what was detected.</summary>
    public string Description { get; set; } = string.Empty;

    /// <summary>Severity of the pattern (0.0 = negligible, 1.0 = critical).</summary>
    public double Severity { get; set; }

    /// <summary>Evidence values that led to the detection (e.g., oscillation frequency, CTE values).</summary>
    public Dictionary<string, double> Evidence { get; set; } = new();

    /// <summary>Which navigation phase this pattern was detected in (null = all phases combined).</summary>
    public TelemetryPhase? DetectedInPhase { get; set; }
}

/// <summary>
/// A single parameter adjustment suggestion.
/// </summary>
public class TuningSuggestion
{
    public Guid Id { get; set; } = Guid.NewGuid();

    /// <summary>
    /// Dot-path to the parameter, e.g., "PurePursuitConfig.LookaheadMin" or "StanleyConfig.K".
    /// </summary>
    public string ParameterPath { get; set; } = string.Empty;

    /// <summary>Display name for the parameter.</summary>
    public string ParameterDisplayName { get; set; } = string.Empty;

    /// <summary>Current value of the parameter.</summary>
    public double CurrentValue { get; set; }

    /// <summary>Suggested new value.</summary>
    public double SuggestedValue { get; set; }

    /// <summary>Human-readable reason for the suggestion.</summary>
    public string Reason { get; set; } = string.Empty;

    /// <summary>Priority of this suggestion.</summary>
    public SuggestionPriority Priority { get; set; }

    /// <summary>Confidence in this suggestion (0.0 - 1.0).</summary>
    public double Confidence { get; set; }

    /// <summary>Which diagnostic pattern(s) triggered this suggestion.</summary>
    public List<DiagnosticCategory> RelatedPatterns { get; set; } = new();

    /// <summary>Expected impact description.</summary>
    public string ExpectedImpact { get; set; } = string.Empty;

    /// <summary>Which navigation phase this suggestion targets (null = general).</summary>
    public TelemetryPhase? TargetPhase { get; set; }

    /// <summary>Percentage change from current to suggested.</summary>
    public double ChangePercent => CurrentValue != 0
        ? ((SuggestedValue - CurrentValue) / Math.Abs(CurrentValue)) * 100.0
        : 0;
}

/// <summary>
/// Per-phase metrics computed from telemetry for phase-aware tuning analysis.
/// </summary>
public class PhaseMetrics
{
    public TelemetryPhase Phase { get; set; }
    public int SampleCount { get; set; }
    public double DurationMs { get; set; }

    // Tracking
    public double CrossTrackErrorRMS { get; set; }
    public double CrossTrackErrorPeak { get; set; }
    public double CrossTrackErrorMean { get; set; }
    public double HeadingErrorRMS { get; set; }
    public double HeadingErrorPeak { get; set; }

    // Smoothness
    public double AngularVelocityStdDev { get; set; }
    public double VelocityStdDev { get; set; }
    public double AccelerationStdDev { get; set; }

    // Goal (FinalApproach/FinalRotation only)
    public double GoalPositionError { get; set; }
    public double GoalHeadingErrorDeg { get; set; }
}

/// <summary>
/// Complete tuning analysis report for a test run.
/// </summary>
public class TuningReport
{
    public Guid Id { get; set; } = Guid.NewGuid();
    public Guid TestRunId { get; set; }
    public DateTime GeneratedAt { get; set; } = DateTime.UtcNow;

    /// <summary>Which controller was active during the test.</summary>
    public PathFollowingController ControllerType { get; set; }

    /// <summary>Overall assessment of the test quality.</summary>
    public string OverallAssessment { get; set; } = string.Empty;

    /// <summary>Detected diagnostic patterns from telemetry analysis.</summary>
    public List<DiagnosticPattern> DetectedPatterns { get; set; } = new();

    /// <summary>Ordered list of suggestions (highest priority first).</summary>
    public List<TuningSuggestion> Suggestions { get; set; } = new();

    /// <summary>Number of telemetry samples analyzed.</summary>
    public int TelemetrySamplesAnalyzed { get; set; }

    /// <summary>Sample count per navigation phase.</summary>
    public Dictionary<TelemetryPhase, int> PhaseSampleCounts { get; set; } = new();

    /// <summary>Per-phase metrics computed from telemetry.</summary>
    public Dictionary<TelemetryPhase, PhaseMetrics> PhaseMetricsMap { get; set; } = new();

    /// <summary>Whether any critical issues were detected.</summary>
    public bool HasCriticalIssues => Suggestions.Any(s => s.Priority == SuggestionPriority.Critical);

    /// <summary>Count of high+ priority suggestions.</summary>
    public int HighPriorityCount => Suggestions.Count(s => s.Priority >= SuggestionPriority.High);
}