using ERPCore.Dtos.Hrm;

namespace ERPCore.Services.Interfaces;

/// <summary>
/// Bidirectional Employee&lt;-&gt;User soft-match/link logic (docs/12-BACKEND-HRM.md A.5,
/// Part B.3.2). Lookups are advisory only; linking is always an explicit, human-confirmed
/// action — never automatic, even on an exact email match.
/// </summary>
public interface IEmployeeUserLinkService
{
    /// <summary>Given an email (typically entered on a Create-User form), find an unlinked Staff record match.</summary>
    Task<EmployeeMatchDto?> FindStaffCandidateByEmailAsync(string email, CancellationToken ct = default);

    /// <summary>Given an email (typically entered on a Create-Employee form), find an unlinked User account match.</summary>
    Task<UserMatchDto?> FindUserCandidateByEmailAsync(string email, CancellationToken ct = default);

    /// <summary>Links an existing Employee to an existing User. Throws EMPLOYEE_ALREADY_LINKED/USER_ALREADY_LINKED if either side is already linked to someone else.</summary>
    Task LinkAsync(int employeeId, int userId, CancellationToken ct = default);

    Task UnlinkAsync(int employeeId, CancellationToken ct = default);
}
