adas-core/adas-core.Application/Services/Interfaces/IAdmissionService.cs

using adas_core.Domain.Models;
using adas_core.Domain.Models.DTO;
using adas_core.Domain.Models.Masters;
using adas_core.Domain.Models.MongoModels;
using adas_core.Domain.Models.Responses;
using MongoDB.Bson;

namespace adas_core.Application.Services.Interfaces;

public interface IAdmissionService : IApiRequestService
{
    /// <summary>
    /// Asynchronously retrieves an admission by its unique identifier, returning <c>null</c> when no matching admission is found.
    /// </summary>
    /// <param name="admissionId">The unique identifier of the admission to retrieve.</param>
    /// <returns>A task that represents the asynchronous operation, containing the <see cref="Admission"/> if found, or <c>null</c> if no admission matches the specified identifier.</returns>
    Task<Admission?> GetAdmissionByIdAsync(ObjectId admissionId);
    /// <summary>
    /// Asynchronously deletes an admission record identified by the specified admission ID.
    /// </summary>
    /// <param name="admissionId">The unique identifier of the admission to delete.</param>
    Task DeleteAdmissionByIdAsync(ObjectId admissionId);
    /// <summary>
    /// Asynchronously deletes the specified admission record.
    /// </summary>
    /// <param name="admission">The admission entity to remove.</param>
    Task DeleteAdmissionAsync(Admission admission);
    /// <summary>
    /// Deletes all admissions associated with the specified unit identifier.
    /// </summary>
    /// <param name="unitId">The identifier of the unit whose admissions will be deleted.</param>
    Task DeleteAdmissionsByUnitId(ObjectId unitId);

    /// <summary>
    /// Asynchronously updates an existing admission record with the provided information.
    /// </summary>
    /// <param name="admission">The admission entity containing the updated data to be persisted.</param>
    /// <returns>A task that represents the asynchronous update operation.</returns>
    Task UpdateAdmissionAsync(Admission admission);
    /// <summary>
    /// Asynchronously retrieves a collection of admissions.
    /// </summary>
    /// <returns>A task that represents the asynchronous operation. The task result contains an enumerable collection of <see cref="Admission"/> objects.</returns>
    Task<IEnumerable<Admission>> GetAdmissionsAsync();
    /// <summary>
    /// Asynchronously inserts a new admission record and returns the created entry, or <see langword="null"/> if the insertion was not performed.
    /// </summary>
    /// <param name="admission">The admission entity to be inserted into the data store.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the inserted <see cref="Admission"/>, or <see langword="null"/> when no record is produced.</returns>
    Task<Admission?> InsertAdmission(Admission admission);
    /// <summary>
    /// Admits a patient based on the provided admission details, optionally registering the patient as new.
    /// </summary>
    /// <param name="admission">The admission information used to process the patient admission.</param>
    /// <param name="isNew">Indicates whether the patient is being admitted for the first time. Defaults to <c>false</c>.</param>
    Task AdmitPatient(Admission admission, bool isNew = false);
    /// <summary>
    /// Processes the return of a patient to the admissions workflow, typically used when a patient needs to be re-queued or reinstated for admission processing.
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient to be returned to admissions.</param>
    Task ReturnPatientToAdmissions(ObjectId patientId);
    /// <summary>
    /// Asynchronously returns a patient to the admissions workflow using the specified admission record.
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient being returned to admissions.</param>
    /// <param name="adm">The admission record associated with the patient being returned.</param>
    Task ReturnPatientToAdmissions(ObjectId patientId, Admission adm);
    /// <summary>
    /// Retrieves a list of admissions associated with the specified patient location.
    /// </summary>
    /// <param name="location">The patient location used to filter the admissions.</param>
    /// <returns>A task that represents the asynchronous operation, containing a list of admissions for the given location.</returns>
    Task<List<Admission>> GetAdmissionByLocation(PatientLocation location);
    /// <summary>
    /// Asynchronously retrieves the list of admissions associated with the specified point of care identifier.
    /// </summary>
    /// <param name="id">The <see cref="ObjectId"/> of the point of care used to filter the admissions.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains a list of <see cref="Admission"/> objects matching the specified point of care id, or an empty list if no admissions are found.</returns>
    Task<List<Admission>> GetAdmissionByPointOfCareId(ObjectId id);
    /// <summary>
    /// Retrieves the list of admissions associated with the specified point of care, localized for the given locale.
    /// </summary>
    /// <param name="pocId">The identifier of the point of care whose admissions are being queried.</param>
    /// <param name="locale">The locale used to localize the returned admission data.</param>
    /// <returns>A task that resolves to the list of admissions matching the point of care and locale; an empty list when no matches are found.</returns>
    Task<List<Admission>> GetAdmissionByPointOfCareIdAndLocale(ObjectId pocId, LocaleEnum locale);
    /// <summary>
    /// Retrieves a list of admissions associated with the specified unit identifier, excluding any Point of Care (PoC) related admissions.
    /// </summary>
    /// <param name="unitId">The unique identifier of the unit whose admissions should be retrieved.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains a list of admissions for the specified unit, excluding PoC admissions.</returns>
    Task<List<Admission>> GetAdmissionByUnitIdWithOutPoC(ObjectId unitId);
    /// <summary>
    /// Asynchronously counts the number of admissions associated with the specified unit identifier.
    /// </summary>
    /// <param name="unitId">The MongoDB ObjectId of the unit whose admissions should be counted.</param>
    /// <returns>A task that represents the asynchronous operation, containing the total count of admissions for the given unit.</returns>
    Task<long> CountAdmissionsByUnitId(ObjectId unitId);

    /// <summary>
    /// Searches for a patient by their patient number within the specified unit, returning the matching patient search result or null if no match is found.
    /// </summary>
    /// <param name="patientNumber">The patient number used to identify the patient.</param>
    /// <param name="unitId">The identifier of the unit in which the patient is being searched.</param>
    /// <returns>A task that returns the matching <see cref="PatientSearch"/> if found; otherwise, null.</returns>
    Task<PatientSearch?> SearchByPatientNumberAndDistinctUnit(string patientNumber, ObjectId unitId);
    /// <summary>
    /// Retrieves the admission record associated with the specified patient number, returning <c>null</c> when no matching admission is found.
    /// </summary>
    /// <param name="patientNumber">The unique patient number used to look up the admission.</param>
    /// <returns>A task that resolves to the matching <see cref="Admission"/>, or <c>null</c> if no admission exists for the given patient number.</returns>
    Task<Admission?> GetAdmissionByPatientNumber(string patientNumber);

    /// <summary>
    /// Updates a patient master list item based on the provided option change and related unit and type information.
    /// </summary>
    /// <param name="opt">The update option master list data transfer object containing the change details.</param>
    /// <param name="unitList">The collection of units associated with the master list item change.</param>
    /// <param name="typeName">The name of the type used to identify the master list item category.</param>
    /// <returns>A task that represents the asynchronous update operation.</returns>
    Task UpdatePatientMasterListItemChange(UpdateOptionMasterListDto opt, IEnumerable<Unit> unitList, string typeName);
    /// <summary>
    /// Deletes a patient master list item identified by the specified options, units, and type name.
    /// </summary>
    /// <param name="opt">The option list used to identify the master list item to delete.</param>
    /// <param name="unitList">The collection of units associated with the master list item.</param>
    /// <param name="typeName">The name of the type associated with the master list item.</param>
    Task DeletePatientMasterListItem(OptionList opt, IEnumerable<Unit> unitList, string typeName);
}