Documentation modifications

adas-core.Test/Customizations/HUVH/UCIN/CalculatedObservationsTest.cs

@@ -13,9 +13,20 @@ using Newtonsoft.Json;
 
 namespace adas_core.Test.Customizations.HUVH.UCIN;
 
+/// <summary>
+/// Test fixture that contains unit tests for the <see cref="CalculatedObservations"/> type.
+/// </summary>
+/// <remarks>
+/// Marked with <c>TestFixture</c> so that the NUnit test runner discovers and executes the contained test methods.
+/// </remarks>
+/// <!-- aidoc:v1 sig=ce3e368 -->
 [TestFixture]
 public class CalculatedObservationsTest
 {
+    /// <summary>
+    /// Initializes the mocked dependencies and configuration required to instantiate <see cref="CalculatedObservations"/> for unit tests, including observation, medicine, and treatment services, the logger, and an <see cref="IOptions{ApiSettings}"/> populated with mapping interventions and complexity observation values deserialized from JSON.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=dee8bf2 body=89278f9 -->
     [SetUp]
     public void Setup()
     {
@@ -1468,6 +1479,10 @@ public class CalculatedObservationsTest
                 Times.Never);
         }
 
+    /// <summary>
+    /// Verifies that when a new "Intervention_In" observation is mapped via <c>Map</c> and the patient's prior "Respiratory_Device_Multivalue" observation is expired (so there is no existing active last observation), a new <see cref="PatientObservation"/> named "Respiratory_Device_Multivalue" is inserted containing the new intervention while the existing expired observation is left untouched.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=4271f27 body=7d4a79d -->
     [Test]
     public async Task Map_WithNewInterventionNoExistingLastIntervention_NewMultiValueObservation()
     {
@@ -1519,6 +1534,13 @@ public class CalculatedObservationsTest
             Times.Once);
     }
 
+    /// <summary>
+    /// Verifies that when a new <c>Intervention_In</c> observation is mapped for a patient that already has an
+    /// active <c>Respiratory_Device_Multivalue</c> observation, the new intervention is appended to the existing
+    /// multi-value observation via <see cref="IObservationService.UpdateObservation"/> rather than inserted as a
+    /// new record through <see cref="IObservationService.InsertObservation"/>.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=4e3257d body=697676f -->
     [Test]
     public async Task Map_WithNewInterventionAddsToExistingMultiValueObservation()
     {
@@ -1805,6 +1827,12 @@ public class CalculatedObservationsTest
                 Times.Once);
         }
 
+    /// <summary>
+    /// Verifies that the <c>Map</c> method persists a "Complexity" <see cref="PatientObservation"/> with value 5
+    /// when an "Intravenous_Routes_Multivalue" entry of "VV central" (contributing 2) and a "Respiratory_Device_Multivalue"
+    /// entry of "Ventilación mecánica Invasiva" (contributing 3) are provided, summing their mapped complexity contributions.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=2e89a15 body=4e1ae0e -->
     [Test]
     public async Task Map_WithIntravenousRoutesAndRespiratoryDeviceMultiValueObservation_CalculatesComplexity_Return5()
     {
@@ -1944,6 +1972,13 @@ public class CalculatedObservationsTest
                 Times.Once);
         }
 
+    /// <summary>
+    /// Verifies that <see cref="PatientObservation"/> values mapped through the calculated observations pipeline
+    /// produce a <c>Complexity</c> observation with value <c>4</c> when a newborn weight observation of <c>600</c>
+    /// is provided and no previous observations exist for the respiratory, intravenous, medication, system,
+    /// or surgery multivalue categories.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=bdf12e7 body=260627c -->
     [Test]
     public async Task Map_WithNewbornWeightObservation_CalculatesComplexity_Return4()
     {
@@ -2034,6 +2069,10 @@ public class CalculatedObservationsTest
                 Times.Once);
         }
 
+    /// <summary>
+    /// Tests that <see cref="CalculateSaturation.Map"/> inserts a diff observation with the calculated difference and a combined pre/post observation when a pre-observation is provided and the matching post-observation is found through <see cref="IObservationService.FindLastObservations"/>.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=1391042 body=6df8725 -->
     [Test]
     public async Task CalculateSaturation_DiffObservation_WhenPreObservationExistsAndPostIsFound_InsertsDiffAndPrePost()
     {
@@ -2082,6 +2121,10 @@ public class CalculatedObservationsTest
             Times.Once);
     }
 
+    /// <summary>
+    /// Verifies that when a post observation is processed and a matching pre observation is found, both a diff observation (with the computed difference value) and a combined pre/post observation (with the pre and post values) are inserted.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=b6cc196 body=fb6ab5b -->
     [Test]
     public async Task CalculateSaturation_DiffObservation_WhenPostObservationExistsAndPreIsFound_InsertsDiffAndPrePost()
     {
@@ -2130,6 +2173,10 @@ public class CalculatedObservationsTest
             Times.Once);
     }
 
+    /// <summary>
+    /// Verifies that <see cref="CalculatedObservations.Map(PatientObservation)"/> does not insert new <see cref="PatientObservation"/> records when only the pre-observation is available for the patient and no matching post-observation is returned by <see cref="IObservationService.FindLastObservations"/>.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=fc1b349 body=1b524a8 -->
     [Test]
     public async Task CalculateSaturation_DiffObservation_WhenOnlyPreObservationExists_DoesNotInsertNewObservations()
     {
@@ -2161,6 +2208,12 @@ public class CalculatedObservationsTest
             x => x.InsertObservation(It.IsAny<PatientObservation>(), It.IsAny<bool>(), It.IsAny<bool>()), Times.Never);
     }
 
+    /// <summary>
+    /// Verifies that <c>CalculateSaturation</c> for a diff observation does not insert new
+    /// <see cref="PatientObservation"/> entries when only the post-observation is found and the
+    /// pre-observation is missing, ensuring no fallback insert occurs in this scenario.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=c544665 body=5c5be3e -->
     [Test]
     public async Task CalculateSaturation_DiffObservation_WhenOnlyPostObservationExists_DoesNotInsertNewObservations()
     {
@@ -2192,6 +2245,10 @@ public class CalculatedObservationsTest
             x => x.InsertObservation(It.IsAny<PatientObservation>(), It.IsAny<bool>(), It.IsAny<bool>()), Times.Never);
     }
 
+    /// <summary>
+    /// Verifies that the saturation difference calculation correctly handles pre and post <see cref="PatientObservation"/> values that differ, producing a "SpO2_Diff" observation with the numeric difference (7.4) and a "SpO2_Pre_Post" observation with both values formatted as "99,5/92,1".
+    /// </summary>
+    /// <!-- aidoc:v1 sig=f1e8f91 body=ed06b26 -->
     [Test]
     public async Task CalculateSaturation_DiffObservation_WithDifferentPrePostValues_CalculatesCorrectDifference()
     {
@@ -2240,6 +2297,14 @@ public class CalculatedObservationsTest
             Times.Once);
     }
 
+    /// <summary>
+    /// Verifies that when mapping a pre-observation whose <see cref="PatientObservation.Value"/> is non-numeric, the
+    /// <c>CalculateSaturation</c> logic treats the pre-value as 0 when computing the difference against the latest
+    /// matching post-observation returned by <see cref="IObservationService.FindLastObservations"/>.
+    /// Confirms that a <c>SpO2_Diff</c> observation is inserted with the value <c>0 - post</c> rounded to two decimals,
+    /// and a <c>SpO2_Pre_Post</c> observation is inserted concatenating the raw pre-value and post-value.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=36a4380 body=95adfa9 -->
     [Test]
     public async Task CalculateSaturation_DiffObservation_WithNonNumericPreValue_TreatsAsZero()
     {
@@ -2382,6 +2447,11 @@ public class CalculatedObservationsTest
                 x => x.InsertObservation(It.IsAny<PatientObservation>(), It.IsAny<bool>(), It.IsAny<bool>()), Times.Never);
         }
 
+    /// <summary>
+    /// Verifies that mapping a <see cref="PatientTreatment"/> whose <see cref="PatientTreatment.EndTime"/> is set yields a result with <see cref="OrderControlType.Dc"/>, overriding the order control that would otherwise be derived from the patient's previously active treatments.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> that completes when the assertions have been evaluated.</returns>
+    /// <!-- aidoc:v1 sig=c43f82e body=7d24ee8 -->
     [Test]
     public async Task Map_TreatmentWithEndTimeSet_OverridesOrderControlFromOldTreatments()
     {
@@ -2406,6 +2476,10 @@ public class CalculatedObservationsTest
         Assert.That(result.OrderControl, Is.EqualTo(OrderControlType.Dc));
     }
 
+    /// <summary>
+    /// Verifies that the map operation inserts an observation when the supplied <see cref="PatientTreatment"/> carries a medication code. The test arranges a treatment with a single requested give code, configures the treatment, medicine, and observation services to return an existing active treatment list, the matching <see cref="Medicine"/>, and no previous observations; then asserts that the resulting <see cref="OrderControlType"/> is <see cref="OrderControlType.Xo"/> and that the observation service is invoked once with a <see cref="PatientObservation"/> whose name equals "Medication_Multivalue" and whose value is a <see cref="String"/> array of length one containing the medication text.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=cc4c529 body=a5d79cd -->
     [Test]
     public async Task Map_TreatmentWithMedication_InsertObservation()
     {