Documentation modifications

adas-core.Infrastructure/Repositories/PatientRepository.cs

@@ -22,6 +22,13 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
 {
     private readonly ApiSettings _apiSettings;
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="PatientRepository"/>, a MongoDB-backed data repository, capturing API configuration from <see cref="IOptions{ApiSettings}"/> and forwarding the <see cref="IMongoDatabase"/> to the base repository constructor.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> whose value supplies the repository's API configuration.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> connection passed to the base class constructor.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="apiSettings"/> is null.</exception>
+    /// <!-- aidoc:v1 sig=113519f body=d2b18a3 -->
     public PatientRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
     {
         if (apiSettings == null) throw new ArgumentNullException(nameof(apiSettings));
@@ -279,6 +286,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
         }
 
 
+    /// <summary>
+    /// Finds a <see cref="Patient"/> by <paramref name="patientNumber"/>, preferring the most recently admitted active patient (one whose <see cref="Patient.DisTime"/> is null) and falling back to the <see cref="Patient"/> record with the most recent non-null <see cref="Patient.DisTime"/> when no active admission exists. Returns null when <paramref name="patientNumber"/> is null, empty, or whitespace, or when no matching record is found.
+    /// </summary>
+    /// <param name="patientNumber">The patient number used to locate the <see cref="Patient"/> record.</param>
+    /// <returns>A <see cref="Task{Patient}"/> that resolves to the matching <see cref="Patient"/>, or null when no record is found.</returns>
+    /// <!-- aidoc:v1 sig=09c89ab body=91862bd -->
     public async Task<Patient?> FindByPatientNumber(string patientNumber)
     {
         if (string.IsNullOrWhiteSpace(patientNumber)) return null;
@@ -305,6 +318,13 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
         return patient;
     }
 
+    /// <summary>
+    /// Searches for a <see cref="Patient"/> by <paramref name="patientNumber"/> whose <see cref="Patient.UnitId"/> differs from <paramref name="unitId"/>, intended to locate a patient identified at a Point of Care but registered in another unit. Returns <c>null</c> when the patient number is blank, when multiple matches are found (since the patient number may be incomplete), or when no match exists; exceptions are logged and also surface as <c>null</c>.
+    /// </summary>
+    /// <param name="patientNumber">The patient number used to look up the <see cref="Patient"/>.</param>
+    /// <param name="unitId">The <see cref="ObjectId"/> of the unit that must be excluded from the match.</param>
+    /// <returns>A <see cref="Task{Patient}"/> resolving to the matching <see cref="Patient"/>, or <c>null</c> when there is no unique match.</returns>
+    /// <!-- aidoc:v1 sig=382b7c8 body=f2b7752 -->
     public async Task<Patient?> SearchByPatientNumberAndDistinctUnit(string patientNumber, ObjectId unitId)
     {
         try
@@ -328,6 +348,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
         }
     }
 
+    /// <summary>
+    /// Retrieves all <see cref="Patient"/> documents that contain at least one procedure considered finished and eligible for archival. A procedure qualifies when its <c>EndDate</c> is not null and the time elapsed since that <c>EndDate</c> exceeds the supplied grace period of <paramref name="archiveProcedureEndDateAfterMinutes"/> minutes relative to the current UTC time.
+    /// </summary>
+    /// <param name="archiveProcedureEndDateAfterMinutes">The grace period, in minutes, added to a procedure's <c>EndDate</c>; the procedure is treated as finished only when the resulting timestamp is earlier than <see cref="DateTime.UtcNow"/>.</param>
+    /// <returns>A <see cref="Task{List{Patient}}"/> containing the patients matching the finished-procedure criteria, or an empty list when no patient has a procedure whose archival grace period has elapsed.</returns>
+    /// <!-- aidoc:v1 sig=8527a2e body=acd9bfe -->
     public async Task<List<Patient>> FindAllPatientWithFinishedProcedures(int archiveProcedureEndDateAfterMinutes)
     {
         var currentDateTime = DateTime.UtcNow;
@@ -359,6 +385,13 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
         return patientsWithFinishedProcedures;
     }
 
+    /// <summary>
+    /// Retrieves all <see cref="Patient"/> records whose tests have finished and whose end date, offset by the specified archive threshold, is earlier than the current UTC time.
+    /// The initial MongoDB filter keeps tests with a non-null EndDate, and the in-memory filter then retains only those whose EndDate plus <paramref name="archiveTestEndDateAfterMinutes"/> minutes is before <see cref="DateTime.UtcNow"/>.
+    /// </summary>
+    /// <param name="archiveTestEndDateAfterMinutes">The number of minutes added to each test's EndDate to determine whether the test is eligible for archival.</param>
+    /// <returns>A <see cref="Task{List{Patient}}"/> containing the patients whose tests meet the finished and archive criteria.</returns>
+    /// <!-- aidoc:v1 sig=c7d3a85 body=8559f5d -->
     public async Task<List<Patient>> FindAllPatientWithFinishedTests(int archiveTestEndDateAfterMinutes)
     {
         var currentDateTime = DateTime.UtcNow;
@@ -389,6 +422,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
         return patientsWithFinishedTests;
     }
 
+    /// <summary>
+    /// Asynchronously retrieves all patients that have at least one finished <see cref="Patient.Treatment"/> whose <see cref="Treatment.EndDate"/> is older than <paramref name="archiveTreatmentEndDateAfterMinutes"/> minutes relative to the current UTC time, using a MongoDB query combined with an in-memory time threshold filter.
+    /// </summary>
+    /// <param name="archiveTreatmentEndDateAfterMinutes">The grace period in minutes that must elapse after a treatment's <see cref="Treatment.EndDate"/> before the patient qualifies for retrieval.</param>
+    /// <returns>A <see cref="Task{List{Patient}}"/> that resolves to the list of <see cref="Patient"/> records whose treatments satisfy the finished-treatment time threshold.</returns>
+    /// <!-- aidoc:v1 sig=6b43cdf body=429c102 -->
     public async Task<List<Patient>> FindAllPatientWithFinishedTreatment(int archiveTreatmentEndDateAfterMinutes)
     {
         var currentDateTime = DateTime.UtcNow;
@@ -414,6 +453,19 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
         return patientsWithFinishedTreatments;
     }
 
+    /// <summary>
+    /// Updates a master list option for all patients belonging to the specified <paramref name="unitIds"/>,
+    /// handling <see cref="MasterListType.DiagnosisList"/>, <see cref="MasterListType.DoctorList"/>,
+    /// and <see cref="MasterListType.OriginList"/> cases by updating the relevant fields and auxiliary fields,
+    /// and returning the updated <see cref="Patient"/> documents. If <paramref name="typeName"/> cannot be parsed
+    /// as a <see cref="MasterListType"/> or the type is not implemented, an empty list is returned.
+    /// </summary>
+    /// <param name="unitIds">The collection of unit identifiers used to scope the update to the affected patients.</param>
+    /// <param name="opt">The DTO containing the existing option and the replacement option values to apply.</param>
+    /// <param name="typeName">The textual name of the <see cref="MasterListType"/> that determines which update path is executed.</param>
+    /// <returns>A <see cref="Task{TResult}"/> containing the updated <see cref="List{Patient}"/> documents,
+    /// or an empty list when no update was performed.</returns>
+    /// <!-- aidoc:v1 sig=afe83cc body=25f24cf -->
     public async Task<List<Patient>> UpdateMasterListOption(List<ObjectId> unitIds, UpdateOptionMasterListDto opt,
         string typeName)
     {
@@ -593,6 +645,14 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
         }
 
 
+    /// <summary>
+    /// Deletes a master list option from <see cref="Patient"/> documents belonging to the specified units, applying the appropriate update logic based on the resolved <see cref="MasterListType"/>. Returns the affected patients for the supported types (<see cref="MasterListType.DiagnosisList"/>, <see cref="MasterListType.DoctorList"/>, and <see cref="MasterListType.OriginList"/>), or an empty collection when <paramref name="typeName"/> cannot be parsed or the type has no handling logic.
+    /// </summary>
+    /// <param name="unitIds">The collection of <see cref="ObjectId"/> values identifying the units whose patients will be affected by the deletion.</param>
+    /// <param name="opt">The <see cref="OptionList"/> option to remove, matched by its <see cref="OptionList.Name"/> (for diagnosis and origin lists) or its <see cref="OptionList.Id"/> (for the doctor list).</param>
+    /// <param name="typeName">The textual name of the master list type, parsed via <see cref="Enum.TryParse{T}"/> with <typeparamref name="T"/> = <see cref="MasterListType"/> to select the update strategy.</param>
+    /// <returns>A <see cref="Task"/> that yields the <see cref="Patient"/> documents modified for the supported <see cref="MasterListType"/> values, or an empty <see cref="List{Patient}"/> when no updates are performed.</returns>
+    /// <!-- aidoc:v1 sig=800d406 body=d26e8f1 -->
     public async Task<IEnumerable<Patient>> DeleteMasterListOption(List<ObjectId> unitIds, OptionList opt,
         string typeName)
     {
@@ -714,6 +774,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
         return new List<Patient>();
     }
 
+    /// <summary>
+    /// Finds the <see cref="Patient"/> associated with the specified <see cref="Patient.PatientId"/>, preferring an active admission (no <see cref="Patient.DisTime"/>) sorted by most recent <see cref="Patient.AdmTime"/>, and falling back to the most recently discharged record when no active admission exists.
+    /// </summary>
+    /// <param name="patientId">The identifier of the patient to locate.</param>
+    /// <returns>A <see cref="Patient"/> instance if found; otherwise, <see langword="null"/> when <paramref name="patientId"/> is null, empty, or whitespace, or when no matching record exists.</returns>
+    /// <!-- aidoc:v1 sig=fca9190 body=71f3c84 -->
     public async Task<Patient?> FindByPatientId(string patientId)
     {
         if (string.IsNullOrWhiteSpace(patientId)) return null;
@@ -729,6 +795,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
         return patient;
     }
 
+    /// <summary>
+    /// Retrieves the most relevant <see cref="Patient"/> record for the specified identifier, prioritizing an active admission (no discharge time) ordered by the latest <see cref="Patient.AdmTime"/>, and falling back to the most recently discharged patient ordered by <see cref="Patient.DisTime"/> when no active admission exists.
+    /// </summary>
+    /// <param name="patientId">The <see cref="ObjectId"/> of the <see cref="Patient"/> to look up.</param>
+    /// <returns>The matching <see cref="Patient"/> if one is found; otherwise, <see langword="null"/>.</returns>
+    /// <!-- aidoc:v1 sig=b9e9549 body=8f9c8ea -->
     public async Task<Patient?> FindByPatientId(ObjectId patientId)
     {
         //Último paciente admitido
@@ -782,6 +854,11 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
             return await result.ToListAsync();
         }
 
+    /// <summary>
+    /// Asynchronously retrieves all <see cref="Patient"/> records whose associated point of care is not a virtual <see cref="VirtualPointOfCare"/>, by performing a lookup against the <c>pointOfCares</c> collection and excluding any bed whose value matches a virtual point of care.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> that resolves to a <see cref="List{Patient}"/> containing the patients located in active (non-virtual) points of care.</returns>
+    /// <!-- aidoc:v1 sig=2479e43 body=f5b7981 -->
     public async Task<List<Patient>> FindInActivePoC()
     {
         var virtualPointOfCareValues = Enum.GetValues(typeof(VirtualPointOfCare)).Cast<VirtualPointOfCare>()
@@ -812,6 +889,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
     }
 
 
+    /// <summary>
+    /// Asynchronously retrieves the <see cref="Patient"/> records whose associated point of care has a bed value matching one of the <see cref="VirtualPointOfCare"/> enum values.
+    /// The lookup is performed through a MongoDB aggregation pipeline that joins the patients collection with the point of care collection and filters by the <c>pointOfCareInfo.bed</c> field.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> that yields a <see cref="List{Patient}"/> containing the patients linked to a point of care whose bed matches any <see cref="VirtualPointOfCare"/> value.</returns>
+    /// <!-- aidoc:v1 sig=1a67064 body=3dc3451 -->
     public async Task<List<Patient>> FindInInactivePoC()
     {
         var virtualPointOfCareValues = Enum.GetValues(typeof(VirtualPointOfCare)).Cast<VirtualPointOfCare>()