using System.Collections.Immutable;
using Common.Documents;
using Connected.Annotations;
using Connected.ServiceModel;

namespace Logistics.Documents.Receive;
/// <summary>
/// Represents service for the <see cref="IReceiveDocument"/> document.
/// </summary>
[Service]
[ServiceUrl(DocumentUrls.Receives)]
public interface IReceiveDocumentService : IDocumentService<int, long>
{
	/// <summary>
	/// Inserts a new <see cref="IReceiveDocument"/>.
	/// </summary>
	/// <param name="args">The arguments containing the properties of the new document.</param>
	/// <returns>The id of the newly inserted document.</returns>
	Task<int> Insert(InsertReceiveDocumentArgs args);
	/// <summary>
	/// Updates <see cref="IReceiveDocument"/> document.
	/// </summary>
	/// <param name="args">The arguments containing changed properties of the document.</param>
	Task Update(UpdateReceiveDocumentArgs args);
	/// <summary>
	/// Performs partial update on the <see cref="IReceiveDocument"/> for the properties specified 
	/// in arguments.
	/// </summary>
	/// <param name="args">The arguments containing properties that need to be updated.</param>
	Task Patch(PatchArgs<int> args);
	/// <summary>
	/// Deletes <see cref="IReceiveDocument"/> from the storage.
	/// </summary>
	/// <param name="args">The arguments containing the id of the document that is about to be deleted.</param>
	Task Delete(PrimaryKeyArgs<int> args);
	/// <summary>
	/// Selects <see cref="IReceiveDocument"/> for the specified id.
	/// </summary>
	/// <param name="args">The arguments containing the id.</param>
	/// <returns><see cref="IReceiveDocument"/> if found, <c>null</c> otherwise.</returns>
	Task<IReceiveDocument?> Select(PrimaryKeyArgs<int> args);
	/// <summary>
	/// Searches <see cref="IReceiveDocument">documents</see> for the specified criteria.
	/// </summary>
	/// <param name="args">The arguments containing the query criteria.</param>
	/// <returns>The list of <see cref="IReceiveDocument"/> documents that matches the search criteria.</returns>
	Task<ImmutableList<IReceiveDocument>> Query(QueryArgs? args);
	/// <summary>
	/// Inserts a new <see cref="IReceiveItem"/> into the <see cref="IReceiveDocument"/> document.
	/// </summary>
	/// <param name="args">The arguments containing the properties of the new item.</param>
	/// <returns>The id of the newly inserted <see cref="IReceiveItem"/> item.</returns>
	Task<long> InsertItem(InsertReceiveItemArgs args);
	/// <summary>
	/// Updates <see cref="IReceiveItem"/>.
	/// </summary>
	/// <param name="args">The arguments containing the properties to be updated.</param>
	Task UpdateItem(UpdateReceiveItemArgs args);
	/// <summary>
	/// Permanently deleted the <see cref="IReceiveItem"/>.
	/// </summary>
	/// <param name="args">The arguments containing the id of the item to be deleted.</param>
	Task DeleteItem(PrimaryKeyArgs<long> args);
	/// <summary>
	/// Queries the <see cref="IReceiveItem"/> items for the specified <see cref="IReceiveDocument"/>.
	/// </summary>
	/// <param name="args">The arguments containing the id of the document for which the items to be
	/// queried.</param>
	/// <returns>The list of items that belong to the specified document.</returns>
	Task<ImmutableList<IReceiveItem>> QueryItems(PrimaryKeyArgs<int> args);
	/// <summary>
	/// Selects the <see cref="IReceiveItem"/> item for the specified id.
	/// </summary>
	/// <param name="args">The arguments containing the id of the item.</param>
	/// <returns>The <see cref="IReceiveItem"/> if found, <c>null</c> otherwise.</returns>
	Task<IReceiveItem?> SelectItem(PrimaryKeyArgs<long> args);
	/// <summary>
	/// Select the <see cref="IReceiveItem"/> for the specified entity and entity id from the 
	/// specified document.
	/// </summary>
	/// <param name="args">The arguments containing criteria values.</param>
	/// <returns>A first <see cref="IReceiveItem"/> that matches the criteria, <c>null</c> otherwise.</returns>
	Task<IReceiveItem?> SelectItem(SelectReceiveItemArgs args);
}