using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;

namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;

/// <summary>
/// CentralUI facade over the central-to-site "Test Bindings" read command.
/// Backs the Test Bindings dialog on the Configure Instance page: on open and
/// on Refresh, the dialog issues one <see cref="ReadAsync"/> per distinct
/// connection (grouped from the page's bindings table) and renders the
/// per-tag outcomes.
/// </summary>
/// <remarks>
/// The service is the trust boundary for the read capability: it enforces the
/// <c>Design</c> role at central before any cross-cluster traffic is
/// generated, because site-side actors do not unwrap the central trust
/// envelope. Transport failures (timeouts, unreachable sites) are translated
/// into a typed <see cref="ReadTagValuesFailure"/> so the dialog can render an
/// inline banner without crashing — same shape as
/// <see cref="IBrowseService"/>.
/// </remarks>
public interface IBindingTester
{
    /// <summary>
    /// Reads the current value of one or more tags on the live server backing
    /// <paramref name="connectionName"/> at <paramref name="siteId"/>. The
    /// caller is expected to group its bindings by connection name and issue
    /// one call per group (in parallel — the dialog uses
    /// <c>Task.WhenAll</c>).
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="connectionName">Name of the site-local data connection — the site's <c>DataConnectionManagerActor</c> indexes its children by name.</param>
    /// <param name="tagPaths">Tag paths to read.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that resolves to the read outcomes for all requested tag paths.</returns>
    Task<ReadTagValuesResult> ReadAsync(
        string siteId,
        string connectionName,
        IReadOnlyList<string> tagPaths,
        CancellationToken ct = default);
}