146 lines
7.5 KiB
C#
146 lines
7.5 KiB
C#
using Butter.Dtos;
|
|
using Butter.Dtos.Person;
|
|
using Butter.Types;
|
|
using Lactose.Models;
|
|
|
|
namespace Lactose.Repositories;
|
|
|
|
/// <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>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
Task SaveAsync(CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Finds a person by their ID.
|
|
/// </summary>
|
|
/// <param name="id">The ID of the person.</param>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
/// <returns>The person if found; otherwise, null.</returns>
|
|
Task<Person?> FindAsync(Guid id, CancellationToken cancellationToken);
|
|
|
|
/// <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>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
/// <returns>The person if found; otherwise, null.</returns>
|
|
Task<Person?> FindVisibleAsync(Guid id, Guid? userId, EAccessLevel accessLevel,
|
|
string? albumSearch, string? albumSortBy, bool albumSortAsc,
|
|
int albumPage, int albumPageSize, CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Finds a person by their name (case-sensitive).
|
|
/// </summary>
|
|
/// <param name="name">The name of the person.</param>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
/// <returns>The person if found; otherwise, null.</returns>
|
|
Task<Person?> FindByNameAsync(string name, CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Finds all people whose names are in the given set.
|
|
/// </summary>
|
|
/// <param name="names">The names to search for.</param>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
/// <returns>A collection of people with matching names (non-deleted only).</returns>
|
|
Task<List<Person>> FindByNamesAsync(IEnumerable<string> names, CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Retrieves all non-deleted people.
|
|
/// </summary>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
/// <returns>The list of all people.</returns>
|
|
Task<List<Person>> GetAllAsync(CancellationToken cancellationToken);
|
|
|
|
/// <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>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
Task<List<Person>> GetAllVisibleAsync(Guid userId, EAccessLevel accessLevel, CancellationToken cancellationToken);
|
|
|
|
/// <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>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
/// <returns>A paginated list of person previews matching the query.</returns>
|
|
Task<List<PersonPreviewDto>> SearchQueryAsync(string query, int page, int pageSize, string? sortBy, bool sortAsc, Guid userId, EAccessLevel accessLevel, CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Finds multiple people by their IDs.
|
|
/// </summary>
|
|
/// <param name="ids">The IDs to find.</param>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
/// <returns>A collection of matching people.</returns>
|
|
Task<List<Person>> FindBulkAsync(IEnumerable<Guid> ids, CancellationToken cancellationToken);
|
|
|
|
/// <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>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
Task MergePeopleAsync(Guid destId, List<Guid> sourceIds, CancellationToken cancellationToken);
|
|
|
|
/// <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>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
/// <returns><see langword="true"/> if the user is a maintainer of the person.</returns>
|
|
Task<bool> IsMaintainerOfAsync(Guid userId, Guid personId, CancellationToken cancellationToken);
|
|
|
|
/// <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>
|
|
/// <param name="cancellationToken">Token to cancel the operation.</param>
|
|
Task SetMaintainersAsync(Guid personId, IEnumerable<Guid> userIds, CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Executes the given operation inside an explicit transaction on the shared database context,
|
|
/// committing on success and rolling back on failure.
|
|
/// </summary>
|
|
/// <typeparam name="TResult">The type returned by the operation.</typeparam>
|
|
/// <param name="operation">The work to run inside the transaction.</param>
|
|
/// <returns>The operation's result, or null if the operation returned null.</returns>
|
|
Task<TResult?> ExecuteInTransactionAsync<TResult>(Func<Task<TResult?>> operation);
|
|
}
|