OrpaonVision/OrpaonVision.Core/LayerRecognition/ILayerRecognitionService.cs

using OrpaonVision.Core.Results;

namespace OrpaonVision.Core.LayerRecognition;

/// <summary>
/// 层识别服务接口。
/// </summary>
public interface ILayerRecognitionService
{
    /// <summary>
    /// 识别当前层级。
    /// </summary>
    /// <param name="inference">推理结果。</param>
    /// <param name="currentLayer">当前层级。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>层级识别结果。</returns>
    Task<Result<LayerRecognitionResult>> RecognizeLayerAsync(InferenceResultDto inference, int currentLayer, CancellationToken cancellationToken = default);

    /// <summary>
    /// 验证层级稳定性。
    /// </summary>
    /// <param name="layerHistory">层级历史记录。</param>
    /// <param name="stabilityWindow">稳定性窗口大小。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>稳定性验证结果。</returns>
    Task<Result<LayerStabilityResult>> ValidateLayerStabilityAsync(IReadOnlyList<LayerHistoryRecord> layerHistory, int stabilityWindow = 5, CancellationToken cancellationToken = default);

    /// <summary>
    /// 检测层级变化。
    /// </summary>
    /// <param name="inference">推理结果。</param>
    /// <param name="currentLayer">当前层级。</param>
    /// <param name="layerHistory">层级历史记录。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>层级变化检测结果。</returns>
    Task<Result<LayerTransitionResult>> DetectLayerTransitionAsync(InferenceResultDto inference, int currentLayer, IReadOnlyList<LayerHistoryRecord> layerHistory, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取层级特征。
    /// </summary>
    /// <param name="inference">推理结果。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>层级特征。</returns>
    Task<Result<LayerFeatures>> ExtractLayerFeaturesAsync(InferenceResultDto inference, CancellationToken cancellationToken = default);

    /// <summary>
    /// 训练层级识别模型。
    /// </summary>
    /// <param name="trainingData">训练数据。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>训练结果。</returns>
    Task<Result<LayerModelTrainingResult>> TrainLayerModelAsync(IReadOnlyList<LayerTrainingData> trainingData, CancellationToken cancellationToken = default);

    /// <summary>
    /// 更新层级识别模型。
    /// </summary>
    /// <param name="modelData">模型数据。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>更新结果。</returns>
    Task<Result> UpdateLayerModelAsync(LayerModelData modelData, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取层级识别统计信息。
    /// </summary>
    /// <param name="startTime">开始时间。</param>
    /// <param name="endTime">结束时间。</param>
    /// <param name="cancellationToken">取消令牌。</param>
    /// <returns>统计信息。</returns>
    Task<Result<LayerRecognitionStatistics>> GetRecognitionStatisticsAsync(DateTime startTime, DateTime endTime, CancellationToken cancellationToken = default);
}

/// <summary>
/// 层级识别结果。
/// </summary>
public sealed class LayerRecognitionResult
{
    /// <summary>
    /// 识别的层级。
    /// </summary>
    public int RecognizedLayer { get; init; }

    /// <summary>
    /// 置信度。
    /// </summary>
    public double Confidence { get; init; }

    /// <summary>
    /// 识别方法。
    /// </summary>
    public LayerRecognitionMethod Method { get; init; }

    /// <summary>
    /// 层级特征。
    /// </summary>
    public LayerFeatures Features { get; init; } = new();

    /// <summary>
    /// 是否为层级变化。
    /// </summary>
    public bool IsLayerTransition { get; init; }

    /// <summary>
    /// 识别时间。
    /// </summary>
    public DateTime RecognitionTimeUtc { get; init; }

    /// <summary>
    /// 详细信息。
    /// </summary>
    public string? Details { get; init; }

    /// <summary>
    /// 扩展属性。
    /// </summary>
    public Dictionary<string, object> ExtendedProperties { get; init; } = new();
}

/// <summary>
/// 层级稳定性结果。
/// </summary>
public sealed class LayerStabilityResult
{
    /// <summary>
    /// 是否稳定。
    /// </summary>
    public bool IsStable { get; init; }

    /// <summary>
    /// 稳定性得分。
    /// </summary>
    public double StabilityScore { get; init; }

    /// <summary>
    /// 主导层级。
    /// </summary>
    public int DominantLayer { get; init; }

    /// <summary>
    /// 层级分布。
    /// </summary>
    public Dictionary<int, double> LayerDistribution { get; init; } = new();

    /// <summary>
    /// 稳定性窗口。
    /// </summary>
    public int StabilityWindow { get; init; }

    /// <summary>
    /// 验证时间。
    /// </summary>
    public DateTime ValidationTimeUtc { get; init; }

    /// <summary>
    /// 详细信息。
    /// </summary>
    public string? Details { get; init; }
}

/// <summary>
/// 层级变化检测结果。
/// </summary>
public sealed class LayerTransitionResult
{
    /// <summary>
    /// 是否检测到层级变化。
    /// </summary>
    public bool HasTransition { get; init; }

    /// <summary>
    /// 原始层级。
    /// </summary>
    public int FromLayer { get; init; }

    /// <summary>
    /// 目标层级。
    /// </summary>
    public int ToLayer { get; init; }

    /// <summary>
    /// 变化置信度。
    /// </summary>
    public double TransitionConfidence { get; init; }

    /// <summary>
    /// 变化类型。
    /// </summary>
    public LayerTransitionType TransitionType { get; init; }

    /// <summary>
    /// 检测时间。
    /// </summary>
    public DateTime DetectionTimeUtc { get; init; }

    /// <summary>
    /// 详细信息。
    /// </summary>
    public string? Details { get; init; }

    /// <summary>
    /// 扩展属性。
    /// </summary>
    public Dictionary<string, object> ExtendedProperties { get; init; } = new();
}

/// <summary>
/// 层级特征。
/// </summary>
public sealed class LayerFeatures
{
    /// <summary>
    /// 目标检测数量。
    /// </summary>
    public int ObjectCount { get; init; }

    /// <summary>
    /// 目标类别分布。
    /// </summary>
    public Dictionary<string, int> ObjectClassDistribution { get; init; } = new();

    /// <summary>
    /// 平均置信度。
    /// </summary>
    public double AverageConfidence { get; init; }

    /// <summary>
    /// 最大置信度。
    /// </summary>
    public double MaxConfidence { get; init; }

    /// <summary>
    /// 目标位置分布。
    /// </summary>
    public List<BoundingBox> BoundingBoxes { get; init; } = new();

    /// <summary>
    /// 图像特征。
    /// </summary>
    public ImageFeatures ImageFeatures { get; init; } = new();

    /// <summary>
    /// 层级特征向量。
    /// </summary>
    public double[] FeatureVector { get; init; } = Array.Empty<double>();

    /// <summary>
    /// 特征提取时间。
    /// </summary>
    public DateTime ExtractionTimeUtc { get; init; }
}

/// <summary>
/// 图像特征。
/// </summary>
public sealed class ImageFeatures
{
    /// <summary>
    /// 亮度均值。
    /// </summary>
    public double BrightnessMean { get; init; }

    /// <summary>
    /// 对比度。
    /// </summary>
    public double Contrast { get; init; }

    /// <summary>
    /// 纹理复杂度。
    /// </summary>
    public double TextureComplexity { get; init; }

    /// <summary>
    /// 边缘密度。
    /// </summary>
    public double EdgeDensity { get; init; }

    /// <summary>
    /// 颜色分布。
    /// </summary>
    public Dictionary<string, double> ColorDistribution { get; init; } = new();

    /// <summary>
    /// 图像尺寸。
    /// </summary>
    public (int Width, int Height) ImageSize { get; init; }

    /// <summary>
    /// 长宽比。
    /// </summary>
    public double AspectRatio { get; init; }
}

/// <summary>
/// 边界框。
/// </summary>
public sealed class BoundingBox
{
    /// <summary>
    /// X坐标。
    /// </summary>
    public double X { get; init; }

    /// <summary>
    /// Y坐标。
    /// </summary>
    public double Y { get; init; }

    /// <summary>
    /// 宽度。
    /// </summary>
    public double Width { get; init; }

    /// <summary>
    /// 高度。
    /// </summary>
    public double Height { get; init; }

    /// <summary>
    /// 置信度。
    /// </summary>
    public double Confidence { get; init; }

    /// <summary>
    /// 类别。
    /// </summary>
    public string Class { get; init; } = string.Empty;

    /// <summary>
    /// 中心点。
    /// </summary>
    public (double X, double Y) Center => (X + Width / 2, Y + Height / 2);

    /// <summary>
    /// 面积。
    /// </summary>
    public double Area => Width * Height;

    /// <summary>
    /// 长宽比。
    /// </summary>
    public double AspectRatio => Width / Height;
}

/// <summary>
/// 层级历史记录。
/// </summary>
public sealed class LayerHistoryRecord
{
    /// <summary>
    /// 记录ID。
    /// </summary>
    public Guid RecordId { get; init; }

    /// <summary>
    /// 层级。
    /// </summary>
    public int Layer { get; init; }

    /// <summary>
    /// 置信度。
    /// </summary>
    public double Confidence { get; init; }

    /// <summary>
    /// 推理结果。
    /// </summary>
    public InferenceResultDto Inference { get; init; } = new();

    /// <summary>
    /// 层级特征。
    /// </summary>
    public LayerFeatures Features { get; init; } = new();

    /// <summary>
    /// 记录时间。
    /// </summary>
    public DateTime RecordTimeUtc { get; init; }

    /// <summary>
    /// 是否为有效记录。
    /// </summary>
    public bool IsValid { get; init; }

    /// <summary>
    /// 扩展属性。
    /// </summary>
    public Dictionary<string, object> ExtendedProperties { get; init; } = new();
}

/// <summary>
/// 层级训练数据。
/// </summary>
public sealed class LayerTrainingData
{
    /// <summary>
    /// 数据ID。
    /// </summary>
    public Guid DataId { get; init; }

    /// <summary>
    /// 目标层级。
    /// </summary>
    public int TargetLayer { get; init; }

    /// <summary>
    /// 推理结果。
    /// </summary>
    public InferenceResultDto Inference { get; init; } = new();

    /// <summary>
    /// 层级特征。
    /// </summary>
    public LayerFeatures Features { get; init; } = new();

    /// <summary>
    /// 数据标签。
    /// </summary>
    public string Label { get; init; } = string.Empty;

    /// <summary>
    /// 创建时间。
    /// </summary>
    public DateTime CreatedAtUtc { get; init; }

    /// <summary>
    /// 是否为验证数据。
    /// </summary>
    public bool IsValidationData { get; init; }

    /// <summary>
    /// 扩展属性。
    /// </summary>
    public Dictionary<string, object> ExtendedProperties { get; init; } = new();
}

/// <summary>
/// 层级模型训练结果。
/// </summary>
public sealed class LayerModelTrainingResult
{
    /// <summary>
    /// 训练ID。
    /// </summary>
    public Guid TrainingId { get; init; }

    /// <summary>
    /// 模型准确率。
    /// </summary>
    public double Accuracy { get; init; }

    /// <summary>
    /// 模型精确率。
    /// </summary>
    public double Precision { get; init; }

    /// <summary>
    /// 模型召回率。
    /// </summary>
    public double Recall { get; init; }

    /// <summary>
    /// F1分数。
    /// </summary>
    public double F1Score { get; init; }

    /// <summary>
    /// 训练样本数量。
    /// </summary>
    public int TrainingSampleCount { get; init; }

    /// <summary>
    /// 验证样本数量。
    /// </summary>
    public int ValidationSampleCount { get; init; }

    /// <summary>
    /// 训练耗时（毫秒）。
    /// </summary>
    public long TrainingElapsedMs { get; init; }

    /// <summary>
    /// 模型版本。
    /// </summary>
    public string ModelVersion { get; init; } = string.Empty;

    /// <summary>
    /// 训练时间。
    /// </summary>
    public DateTime TrainingTimeUtc { get; init; }

    /// <summary>
    /// 详细信息。
    /// </summary>
    public string? Details { get; init; }

    /// <summary>
    /// 扩展属性。
    /// </summary>
    public Dictionary<string, object> ExtendedProperties { get; init; } = new();
}

/// <summary>
/// 层级模型数据。
/// </summary>
public sealed class LayerModelData
{
    /// <summary>
    /// 模型ID。
    /// </summary>
    public Guid ModelId { get; init; }

    /// <summary>
    /// 模型版本。
    /// </summary>
    public string Version { get; init; } = string.Empty;

    /// <summary>
    /// 模型类型。
    /// </summary>
    public LayerModelType ModelType { get; init; }

    /// <summary>
    /// 模型数据。
    /// </summary>
    public byte[] ModelData { get; init; } = Array.Empty<byte>();

    /// <summary>
    /// 模型参数。
    /// </summary>
    public Dictionary<string, object> ModelParameters { get; init; } = new();

    /// <summary>
    /// 特征提取器配置。
    /// </summary>
    public Dictionary<string, object> FeatureExtractorConfig { get; init; } = new();

    /// <summary>
    /// 创建时间。
    /// </summary>
    public DateTime CreatedAtUtc { get; init; }

    /// <summary>
    /// 是否启用。
    /// </summary>
    public bool IsEnabled { get; init; }

    /// <summary>
    /// 扩展属性。
    /// </summary>
    public Dictionary<string, object> ExtendedProperties { get; init; } = new();
}

/// <summary>
/// 层级识别统计信息。
/// </summary>
public sealed class LayerRecognitionStatistics
{
    /// <summary>
    /// 总识别次数。
    /// </summary>
    public int TotalRecognitions { get; init; }

    /// <summary>
    /// 成功识别次数。
    /// </summary>
    public int SuccessfulRecognitions { get; init; }

    /// <summary>
    /// 失败识别次数。
    /// </summary>
    public int FailedRecognitions { get; init; }

    /// <summary>
    /// 识别准确率。
    /// </summary>
    public double Accuracy { get; init; }

    /// <summary>
    /// 平均置信度。
    /// </summary>
    public double AverageConfidence { get; init; }

    /// <summary>
    /// 层级变化次数。
    /// </summary>
    public int LayerTransitions { get; init; }

    /// <summary>
    /// 按层级分组的统计。
    /// </summary>
    public Dictionary<int, LayerStatistics> ByLayer { get; init; } = new();

    /// <summary>
    /// 按方法分组的统计。
    /// </summary>
    public Dictionary<LayerRecognitionMethod, MethodStatistics> ByMethod { get; init; } = new();

    /// <summary>
    /// 按时间分组的统计。
    /// </summary>
    public Dictionary<DateTime, TimeStatistics> ByTime { get; init; } = new();

    /// <summary>
    /// 统计开始时间。
    /// </summary>
    public DateTime StartTimeUtc { get; init; }

    /// <summary>
    /// 统计结束时间。
    /// </summary>
    public DateTime EndTimeUtc { get; init; }
}

/// <summary>
/// 层级统计。
/// </summary>
public sealed class LayerStatistics
{
    /// <summary>
    /// 层级。
    /// </summary>
    public int Layer { get; init; }

    /// <summary>
    /// 识别次数。
    /// </summary>
    public int RecognitionCount { get; init; }

    /// <summary>
    /// 成功次数。
    /// </summary>
    public int SuccessCount { get; init; }

    /// <summary>
    /// 准确率。
    /// </summary>
    public double Accuracy { get; init; }

    /// <summary>
    /// 平均置信度。
    /// </summary>
    public double AverageConfidence { get; init; }
}

/// <summary>
/// 方法统计。
/// </summary>
public sealed class MethodStatistics
{
    /// <summary>
    /// 识别方法。
    /// </summary>
    public LayerRecognitionMethod Method { get; init; }

    /// <summary>
    /// 使用次数。
    /// </summary>
    public int UsageCount { get; init; }

    /// <summary>
    /// 成功次数。
    /// </summary>
    public int SuccessCount { get; init; }

    /// <summary>
    /// 准确率。
    /// </summary>
    public double Accuracy { get; init; }

    /// <summary>
    /// 平均耗时（毫秒）。
    /// </summary>
    public double AverageElapsedMs { get; init; }
}

/// <summary>
/// 时间统计。
/// </summary>
public sealed class TimeStatistics
{
    /// <summary>
    /// 时间。
    /// </summary>
    public DateTime Time { get; init; }

    /// <summary>
    /// 识别次数。
    /// </summary>
    public int RecognitionCount { get; init; }

    /// <summary>
    /// 成功次数。
    /// </summary>
    public int SuccessCount { get; init; }

    /// <summary>
    /// 层级变化次数。
    /// </summary>
    public int LayerTransitions { get; init; }
}

/// <summary>
/// 层级识别方法。
/// </summary>
public enum LayerRecognitionMethod
{
    /// <summary>
    /// 基于规则。
    /// </summary>
    RuleBased = 0,

    /// <summary>
    /// 基于机器学习。
    /// </summary>
    MachineLearning = 1,

    /// <summary>
    /// 基于深度学习。
    /// </summary>
    DeepLearning = 2,

    /// <summary>
    /// 基于特征匹配。
    /// </summary>
    FeatureMatching = 3,

    /// <summary>
    /// 混合方法。
    /// </summary>
    Hybrid = 4
}

/// <summary>
/// 层级变化类型。
/// </summary>
public enum LayerTransitionType
{
    /// <summary>
    /// 正常切层。
    /// </summary>
    Normal = 0,

    /// <summary>
    /// 跳层。
    /// </summary>
    Skip = 1,

    /// <summary>
    /// 回退。
    /// </summary>
    Backward = 2,

    /// <summary>
    /// 重复。
    /// </summary>
    Duplicate = 3,

    /// <summary>
    /// 异常。
    /// </summary>
    Abnormal = 4
}

/// <summary>
/// 层级模型类型。
/// </summary>
public enum LayerModelType
{
    /// <summary>
    /// 决策树。
    /// </summary>
    DecisionTree = 0,

    /// <summary>
    /// 随机森林。
    /// </summary>
    RandomForest = 1,

    /// <summary>
    /// 支持向量机。
    /// </summary>
    SupportVectorMachine = 2,

    /// <summary>
    /// 神经网络。
    /// </summary>
    NeuralNetwork = 3,

    /// <summary>
    /// 卷积神经网络。
    /// </summary>
    ConvolutionalNeuralNetwork = 4,

    /// <summary>
    /// 梯度提升。
    /// </summary>
    GradientBoosting = 5
}