using System.Runtime.CompilerServices;

namespace LehrerApp.Desktop.Services.Mcp;

/// <summary>
/// Zeigt dem Nutzer eine über MCP vorgeschlagene Änderung an, bevor sie tatsächlich geschrieben
/// wird — Sicherheitsmodell aus dem Planungsdokument: "Tool-Aufruf erzeugt einen Vorschlag/Diff,
/// der im Avalonia-Client als Bestätigungsdialog angezeigt wird, [...] kein 'silent write' durch
/// das Modell." Als Interface gehalten, damit Write-Tool-Tests ohne echtes UI laufen können (siehe
/// <see cref="AvaloniaMcpConfirmationService"/> für die produktive Implementierung).
/// </summary>
public interface IMcpConfirmationService
{
    /// <param name="operationKey">Identifiziert die Art der Operation für eine mögliche
    /// Sitzungsfreigabe ("diese Aktion für den Rest der Sitzung nicht mehr nachfragen") — bewusst
    /// per <see cref="CallerMemberNameAttribute"/> automatisch befüllt (der Name der aufrufenden
    /// Tool-Methode, z.B. "AddLessonPhase"), damit kein Aufrufer diesen Parameter selbst pflegen
    /// muss. Nicht Teil des MCP-Wire-Protokolls, rein internes Bestätigungs-Bookkeeping.</param>
    /// <param name="allowSessionTrust">False für die eine bewusste Ausnahme, bei der eine
    /// Sitzungsfreigabe nicht angeboten werden soll (Nutzer-Entscheidung zu
    /// <c>get_named_untis_absence_pattern</c>: eine namentliche Fehlzeitenauskunft muss JEDES MAL
    /// einzeln bestätigt werden, nie pauschal für die restliche Sitzung) — weder die vorherige
    /// Prüfung auf eine bereits bestehende Freigabe noch das Setzen einer neuen finden dann statt,
    /// unabhängig davon, ob zuvor schon "alle Aktionen" freigegeben wurde.</param>
    /// <returns>true, wenn der Nutzer bestätigt hat (direkt oder über eine bereits erteilte
    /// Sitzungsfreigabe); false bei Ablehnung, Timeout oder falls kein Hauptfenster verfügbar ist
    /// (z.B. während des DB-Passwort-Prompts beim Start).</returns>
    Task<bool> ConfirmAsync(string title, string message, CancellationToken ct,
        [CallerMemberName] string operationKey = "", bool allowSessionTrust = true);
}