bom-local-service/Models/CacheUpdateStatus.cs

namespace BomLocalService.Models;

/// <summary>
/// Represents the current phase of a cache update operation.
/// </summary>
public enum CacheUpdatePhase
{
    Initializing,      // Browser setup, navigation (0-20% of time)
    CapturingFrames,   // Frame capture loop (20-95% of time) 
    Saving            // Metadata, cleanup (95-100% of time)
}

/// <summary>
/// Status information about a cache update operation for a location.
/// Returned when manually triggering a cache refresh via the refresh endpoint.
/// </summary>
public class CacheUpdateStatus
{
    /// <summary>
    /// Indicates whether a background cache update was triggered.
    /// True if the cache was missing or stale and an update was initiated.
    /// False if the cache is valid and no update was needed.
    /// </summary>
    public bool UpdateTriggered { get; set; }

    /// <summary>
    /// Indicates whether cached screenshot files exist for this location.
    /// True if PNG screenshot files are found in the cache directory.
    /// False if no cached files exist for this location.
    /// </summary>
    public bool CacheExists { get; set; }

    /// <summary>
    /// Indicates whether the existing cache is still valid (not expired).
    /// Cache is considered valid if the observation time plus expiration buffer (typically 15.5 minutes)
    /// is still in the future. BOM updates observations every 15 minutes, so cache expiration
    /// includes a small buffer to account for timing variations.
    /// True if cache exists and is still valid, false if cache is missing or expired.
    /// </summary>
    public bool CacheIsValid { get; set; }

    /// <summary>
    /// The UTC timestamp when the current cache will expire and should be refreshed.
    /// Calculated as: ObservationTime + CacheExpirationMinutes (typically observation time + 15.5 minutes).
    /// Null if no cache exists or metadata is not available.
    /// </summary>
    public DateTime? CacheExpiresAt { get; set; }

    /// <summary>
    /// The UTC timestamp when the next cache update should occur.
    /// If cache is valid: equals CacheExpiresAt (when current cache expires).
    /// If cache is invalid/missing: equals current time + CacheExpirationMinutes (when background update will complete).
    /// Null if cache is valid and CacheExpiresAt is null.
    /// </summary>
    public DateTime? NextUpdateTime { get; set; }

    /// <summary>
    /// Human-readable message describing the cache status and action taken.
    /// Possible values:
    /// - "Cache is valid, no update needed" - Cache exists and is still fresh
    /// - "Cache is stale, update triggered" - Cache exists but expired, update initiated
    /// - "No cache exists, update triggered" - No cache found, update initiated
    /// - "Cache update already in progress" - An update is currently running
    /// - "Cache update failed" - An update was attempted but failed (check Error property)
    /// </summary>
    public string? Message { get; set; }

    /// <summary>
    /// Indicates whether the last cache update attempt failed.
    /// True if an update was triggered but encountered an error.
    /// </summary>
    public bool UpdateFailed { get; set; }

    /// <summary>
    /// Error information if the cache update failed.
    /// Contains error code, message, and details about what went wrong.
    /// Null if no error occurred or if update hasn't been attempted yet.
    /// </summary>
    public string? Error { get; set; }

    /// <summary>
    /// Error code for programmatic handling of update failures.
    /// Examples: "SCRAPING_ERROR", "BROWSER_ERROR", "STORAGE_ERROR", "TIMEOUT_ERROR"
    /// Null if no error occurred.
    /// </summary>
    public string? ErrorCode { get; set; }

    /// <summary>
    /// Timestamp when the last update attempt was made (UTC).
    /// Null if no update has been attempted yet.
    /// </summary>
    public DateTime? LastUpdateAttempt { get; set; }
}