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

using adas_core.Domain.Models;
using adas_core.Domain.Models.MongoModels;
using MongoDB.Bson;
using MongoDB.Driver;

namespace adas_core.Application.Services.Interfaces;

public interface IAppointmentService : IApiRequestService
{
    /// <summary>
    /// Asynchronously retrieves the list of patient appointments associated with the specified location.
    /// </summary>
    /// <param name="location">The patient location used to filter and locate the relevant appointments.</param>
    /// <returns>A task that represents the asynchronous operation, containing a list of <see cref="PatientAppointment"/> items matching the given location.</returns>
    /// <!-- aidoc:v1 sig=8d1c435 -->
    Task<List<PatientAppointment>> FindByLocation(PatientLocation location);
    /// <summary>
    /// Retrieves all appointments associated with the specified patient asynchronously.
    /// </summary>
    /// <param name="patientId">The identifier of the patient whose appointments are being retrieved.</param>
    /// <returns>A task that represents the asynchronous operation, containing a list of <see cref="PatientAppointment"/> entries for the patient.</returns>
    /// <!-- aidoc:v1 sig=44280ba -->
    Task<List<PatientAppointment>> GetByPatient(ObjectId patientId);
    /// <summary>
    /// Retrieves the list of patient appointments scheduled for today for the specified patient.
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient whose appointments are being queried.</param>
    /// <param name="ct">A cancellation token to observe while waiting for the task to complete.</param>
    /// <returns>A task that represents the asynchronous operation, containing a list of <see cref="PatientAppointment"/> entries for the given patient for the current day.</returns>
    /// <!-- aidoc:v1 sig=4fb06f0 -->
    Task<List<PatientAppointment>> GetTodayByPatient(ObjectId patientId, CancellationToken ct = default);
    /// <summary>
    /// Retrieves the list of patient appointments scheduled for today at the specified point of care.
    /// </summary>
    /// <param name="pocId">The identifier of the point of care whose appointments will be returned.</param>
    /// <param name="ct">The cancellation token used to cancel the asynchronous operation.</param>
    /// <returns>A task that represents the asynchronous operation, containing a list of today's patient appointments for the specified point of care.</returns>
    /// <!-- aidoc:v1 sig=b1e7397 -->
    Task<List<PatientAppointment>> GetTodayByPoc(ObjectId pocId, CancellationToken ct = default);
    /// <summary>
    /// Asynchronously finds all <see cref="PatientAppointment"/> records associated with the specified patient identifier.
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient whose appointments are being retrieved.</param>
    /// <returns>A task that represents the asynchronous operation, containing an <see cref="IAsyncCursor{TDocument}"/> for iterating over the matching <see cref="PatientAppointment"/> documents.</returns>
    /// <!-- aidoc:v1 sig=2d5cd9f -->
    Task<IAsyncCursor<PatientAppointment>> FindByPatientIdAsync(ObjectId patientId);
    /// <summary>
    /// Asynchronously archives the specified patient, marking the record as archived in the system.
    /// </summary>
    /// <param name="patient">The patient whose record should be archived.</param>
    /// <!-- aidoc:v1 sig=52c2373 -->
    Task Archive(Patient patient);
    /// <summary>
    /// Asynchronously archives records associated with the specified patient identifier.
    /// </summary>
    /// <param name="id">The <see cref="ObjectId"/> of the patient whose related records should be archived.</param>
    /// <!-- aidoc:v1 sig=e5916ec -->
    Task ArchiveByPatientId(ObjectId id);
    /// <summary>
    /// Deletes a record associated with the specified patient identifier.
    /// </summary>
    /// <param name="id">The <see cref="ObjectId"/> of the patient whose related record should be removed.</param>
    /// <!-- aidoc:v1 sig=d457cb9 -->
    Task DeleteByPatientId(ObjectId id);
    /// <summary>
    /// Processes an incoming API request in the context of the specified patient, handling the required business logic and returning when the processing completes.
    /// </summary>
    /// <param name="apiRequest">The API request to be processed.</param>
    /// <param name="patient">The patient associated with the API request.</param>
    /// <!-- aidoc:v1 sig=eae6711 -->
    Task ProcessApiRequest(ApiRequest apiRequest, Patient patient);
    /// <summary>
    /// Updates multiple records by replacing the old <see cref="ObjectId"/> with the new one for the field identified by <paramref name="nameId"/>.
    /// </summary>
    /// <param name="nameId">The name of the field whose <see cref="ObjectId"/> value should be updated.</param>
    /// <param name="id">The new <see cref="ObjectId"/> value to set on matching records.</param>
    /// <param name="oldId">The existing <see cref="ObjectId"/> value to be replaced.</param>
    /// <!-- aidoc:v1 sig=24ef97c -->
    Task UpdateManyObjectId(string nameId, ObjectId id, ObjectId oldId);
}