namespace QuantEngine.Core.Interfaces;

/// <summary>
/// Data collection repository (Dapper + PostgreSQL).
/// Higher-level abstraction over IDataCollectionStore for Web API consumers.
/// </summary>
public interface ICollectionRepository
{
    /// <summary>
    /// Save new collection run.
    /// </summary>
    Task SaveRunAsync(CollectionRunRecord run);

    /// <summary>
    /// Update run with completion status.
    /// </summary>
    Task UpdateRunStatusAsync(string runId, string status, string? finishedAt = null, int? totalSnapshots = null, int? totalErrors = null);

    /// <summary>
    /// Save collection snapshot.
    /// </summary>
    Task SaveSnapshotAsync(CollectionSnapshotRecord snapshot);

    /// <summary>
    /// Save collection error.
    /// </summary>
    Task SaveErrorAsync(CollectionErrorRecord error);

    /// <summary>
    /// Fetch recent collection runs for UI dashboard.
    /// </summary>
    /// <param name="limit">Number of runs to return (default: 20)</param>
    Task<List<CollectionRunRecord>> GetRecentRunsAsync(int limit = 20);

    /// <summary>
    /// Fetch snapshots for a specific run.
    /// </summary>
    Task<List<CollectionSnapshotRecord>> GetRunSnapshotsAsync(string runId);

    /// <summary>
    /// Fetch errors for a specific run.
    /// </summary>
    /// <param name="runId">Run ID</param>
    /// <param name="limit">Max errors to return (default: 50)</param>
    Task<List<CollectionErrorRecord>> GetRunErrorsAsync(string runId, int limit = 50);

    /// <summary>
    /// Get collection pipeline dashboard state for Web UI.
    /// </summary>
    Task<CollectionDashboardStateRecord> GetDashboardStateAsync();

    /// <summary>
    /// Fetch latest snapshots for a ticker across all datasets.
    /// </summary>
    Task<List<CollectionSnapshotRecord>> GetLatestSnapshotsForTickerAsync(string ticker, int limit = 10);
}