using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace ZB.MOM.WW.LmxOpcUa.Host.Domain
{
    /// <summary>
    ///     Interface for Galaxy repository database queries. (GR-001 through GR-004)
    /// </summary>
    public interface IGalaxyRepository
    {
        /// <summary>
        ///     Retrieves the Galaxy object hierarchy used to construct the OPC UA browse tree.
        /// </summary>
        /// <param name="ct">A token that cancels the repository query.</param>
        /// <returns>A list of Galaxy objects ordered for address-space construction.</returns>
        Task<List<GalaxyObjectInfo>> GetHierarchyAsync(CancellationToken ct = default);

        /// <summary>
        ///     Retrieves the Galaxy attributes that become OPC UA variables under the object hierarchy.
        /// </summary>
        /// <param name="ct">A token that cancels the repository query.</param>
        /// <returns>A list of attribute definitions with MXAccess references and type metadata.</returns>
        Task<List<GalaxyAttributeInfo>> GetAttributesAsync(CancellationToken ct = default);

        /// <summary>
        ///     Gets the last Galaxy deploy timestamp used to detect metadata changes that require an address-space rebuild.
        /// </summary>
        /// <param name="ct">A token that cancels the repository query.</param>
        /// <returns>The latest deploy timestamp, or <see langword="null" /> when it cannot be determined.</returns>
        Task<DateTime?> GetLastDeployTimeAsync(CancellationToken ct = default);

        /// <summary>
        ///     Verifies that the service can reach the Galaxy repository before it attempts to build the address space.
        /// </summary>
        /// <param name="ct">A token that cancels the connectivity check.</param>
        /// <returns><see langword="true" /> when repository access succeeds; otherwise, <see langword="false" />.</returns>
        Task<bool> TestConnectionAsync(CancellationToken ct = default);

        /// <summary>
        ///     Occurs when the repository detects a Galaxy deployment change that should trigger an OPC UA rebuild.
        /// </summary>
        event Action? OnGalaxyChanged;
    }
}