MilkyShots/Lactose/Repositories/IPersonRepository.cs

using Butter.Dtos;
using Butter.Dtos.Person;
using Butter.Types;
using Lactose.Models;

/// <summary>
/// Interface for person repository operations.
/// </summary>
public interface IPersonRepository : IDisposable {
    /// <summary>
    /// Inserts a new person into the database.
    /// </summary>
    /// <param name="person">The person to insert.</param>
    void Insert(Person person);

    /// <summary>
    /// Saves all pending changes to the database.
    /// </summary>
    void Save();

    /// <summary>
    /// Finds a person by their ID.
    /// </summary>
    /// <param name="id">The ID of the person.</param>
    /// <returns>The person if found; otherwise, null.</returns>
    Person? Find(Guid id);

    /// <summary>
    /// Finds a person by their ID with albums and assets filtered by the requesting user's access level.
    /// </summary>
    /// <param name="id">The ID of the person.</param>
    /// <param name="userId">The requesting user's ID for visibility-scoped filtering.</param>
    /// <param name="accessLevel">The requesting user's access level.</param>
    /// <param name="albumSearch">Optional search term to filter albums by title.</param>
    /// <param name="albumSortBy">Optional field to sort albums by ("name", "created", "updated", "assets").</param>
    /// <param name="albumSortAsc">Whether to sort albums ascending.</param>
    /// <param name="albumPage">Zero-based page number for album pagination.</param>
    /// <param name="albumPageSize">Number of albums per page (default 150, max 250).</param>
    /// <returns>The person if found; otherwise, null.</returns>
    Person? FindVisible(Guid id, Guid? userId = null, EAccessLevel accessLevel = EAccessLevel.User,
        string? albumSearch = null, string? albumSortBy = null, bool albumSortAsc = true,
        int albumPage = 0, int albumPageSize = PagedParametersDto.MaxPageSize);

    /// <summary>
    /// Finds a person by their name (case-sensitive).
    /// </summary>
    /// <param name="name">The name of the person.</param>
    /// <returns>The person if found; otherwise, null.</returns>
    Person? FindByName(string name);

    /// <summary>
    /// Finds all people whose names are in the given set.
    /// </summary>
    /// <param name="names">The names to search for.</param>
    /// <returns>A collection of people with matching names (non-deleted only).</returns>
    IEnumerable<Person> FindByNames(IEnumerable<string> names);

    /// <summary>
    /// Retrieves all non-deleted people.
    /// </summary>
    IEnumerable<Person> GetAll();

    /// <summary>
    /// Retrieves all non-deleted people that have at least one album with visible assets for the given user.
    /// For <see cref="EAccessLevel.Curator"/> and <see cref="EAccessLevel.Admin"/>, returns all people.
    /// </summary>
    /// <param name="userId">The current user's ID.</param>
    /// <param name="accessLevel">The current user's access level.</param>
    IEnumerable<Person> GetAllVisible(Guid userId, EAccessLevel accessLevel);

    /// <summary>
    /// Searches for people based on a query string with optional sorting and pagination.
    /// Respects access-level filtering for regular users.
    /// </summary>
    /// <param name="query">The search query string to filter by name.</param>
    /// <param name="page">The page number for pagination (default is 0).</param>
    /// <param name="pageSize">The number of results per page (default is 30).</param>
    /// <param name="sortBy">The field to sort by (e.g. "name", "created", "albums"). When <c>null</c>, defaults to name ascending.</param>
    /// <param name="sortAsc">Whether to sort ascending. Default is <c>true</c>.</param>
    /// <param name="userId">The current user's ID for access-level filtering.</param>
    /// <param name="accessLevel">The current user's access level.</param>
    /// <returns>A paginated list of person previews matching the query.</returns>
    IEnumerable<PersonPreviewDto> SearchQuery(string query, int page = 0, int pageSize = 30, string? sortBy = null, bool sortAsc = true, Guid userId = default, EAccessLevel accessLevel = EAccessLevel.User);

    /// <summary>
    /// Finds multiple people by their IDs.
    /// </summary>
    /// <param name="ids">The IDs to find.</param>
    /// <returns>A collection of matching people.</returns>
    IEnumerable<Person> FindBulk(IEnumerable<Guid> ids);

    /// <summary>
    /// Merges multiple source people into a destination person.
    /// Albums, faces, and maintainers are reassigned to the destination, then source people are hard-deleted.
    /// </summary>
    /// <param name="destId">The ID of the destination person.</param>
    /// <param name="sourceIds">The IDs of the source people to merge.</param>
    void MergePeople(Guid destId, List<Guid> sourceIds);

    /// <summary>
    /// Removes a person from the database.
    /// </summary>
    /// <param name="person">The person to remove.</param>
    void Remove(Person person);

    /// <summary>
    /// Checks whether a user is a maintainer of a specific person.
    /// </summary>
    /// <param name="userId">The user ID to check.</param>
    /// <param name="personId">The person ID to check.</param>
    /// <returns><see langword="true"/> if the user is a maintainer of the person.</returns>
    bool IsMaintainerOf(Guid userId, Guid personId);

    /// <summary>
    /// Sets the list of user IDs that maintain this person.
    /// Replaces any existing maintainer assignments.
    /// </summary>
    /// <param name="personId">The person ID.</param>
    /// <param name="userIds">The user IDs to assign as maintainers.</param>
    void SetMaintainers(Guid personId, IEnumerable<Guid> userIds);
}