namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;

/// <summary>
/// Resolves the <c>Actor</c> for an audit row from the current authenticated
/// principal (Phase 3 of the audit re-architecture). User-facing emit sites
/// (the inbound API middleware on a cookie/LDAP-authenticated request) read
/// <see cref="CurrentActor"/> so the canonical <c>AuditEvent.Actor</c> records
/// the real authenticated user, rather than a generic system/identity fallback.
/// </summary>
/// <remarks>
/// <para>The seam is deliberately ASP.NET-free (a plain <c>string?</c>) so it can
/// live in Commons and be consumed by any project without pulling an HTTP
/// dependency. The HTTP-backed implementation
/// (<c>ZB.MOM.WW.ScadaBridge.Security.HttpAuditActorAccessor</c>) reads the
/// authenticated principal off <c>IHttpContextAccessor.HttpContext?.User</c>.</para>
/// <para>This seam is for the <em>authenticated, interactive</em> actor only.
/// System-originated emitters (script/notification/db-outbound) keep their own
/// system actor/fallback and do NOT consult this accessor — there is no
/// interactive principal to read in those flows.</para>
/// </remarks>
public interface IAuditActorAccessor
{
    /// <summary>
    /// The actor string for the currently authenticated principal, or
    /// <c>null</c> when there is no authenticated interactive user (no ambient
    /// request, or an unauthenticated / auth-failure request). A null result
    /// signals the caller to fall back to its existing actor (API-key name,
    /// "system", etc.) — an unauthenticated principal is never echoed back.
    /// </summary>
    string? CurrentActor { get; }
}