update docs and prep for frontend

VigilCareClinicalAPI/Controllers/EncountersController.cs

@@ -13,6 +13,59 @@ public class EncountersController : ControllerBase
 
     public EncountersController(IEncounterService encounters) => _encounters = encounters;
 
+    /// <summary>
+    /// Lists encounters for ward dashboards with denormalized clinical summary fields.
+    /// </summary>
+    /// <param name="status">Optional status filter (DB literal, e.g. ACTIVE).</param>
+    /// <param name="department">Optional department filter (DB literal, e.g. ICU).</param>
+    /// <param name="page">Page number (1-based).</param>
+    /// <param name="pageSize">Results per page.</param>
+    [HttpGet]
+    [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status400BadRequest)]
+    public async Task<IActionResult> List(
+        [FromQuery] string? status,
+        [FromQuery] string? department,
+        [FromQuery] int page = 1,
+        [FromQuery] int pageSize = 20)
+    {
+        EncounterStatus? parsedStatus = null;
+        if (!string.IsNullOrEmpty(status))
+        {
+            try
+            {
+                parsedStatus = EncounterStatusExtensions.FromDbString(status);
+            }
+            catch (ArgumentOutOfRangeException)
+            {
+                return BadRequest(ApiResponse<object>.Fail(400, "Invalid status filter.", "INVALID_STATUS"));
+            }
+        }
+
+        Department? parsedDepartment = null;
+        if (!string.IsNullOrEmpty(department))
+        {
+            try
+            {
+                parsedDepartment = DepartmentExtensions.FromDbString(department);
+            }
+            catch (ArgumentOutOfRangeException)
+            {
+                return BadRequest(ApiResponse<object>.Fail(400, "Invalid department filter.", "INVALID_DEPARTMENT"));
+            }
+        }
+
+        var result = await _encounters.ListAsync(parsedStatus, parsedDepartment, page, pageSize);
+        return Ok(ApiResponse<object>.Ok(new
+        {
+            items = result.Items,
+            page = result.Page,
+            pageSize = result.PageSize,
+            totalCount = result.TotalCount,
+            totalPages = result.TotalPages
+        }));
+    }
+
     /// <summary>
     /// Gets an encounter with patient, recent observations, and open alerts.
     /// </summary>