From 75969a1e3da8de1fd6a8f5209164c38435be2424 Mon Sep 17 00:00:00 2001
From: Arthur Bassi <arthur.winiarski.ranger@outlook.com>
Date: Tue, 21 Jul 2026 09:33:24 -0300
Subject: [PATCH] docs(work-orders): clarify board filter precedence and
 dispatcher lookup

Document myWorkOrders overriding dispatchers, weekend dayGroup null contract, and that dispatcher lookups currently return all users. Map service ArgumentException to 400 for consistency.
---
 .../Controllers/WorkOrderController.cs        | 39 +++++++++++++------
 .../Helpers/WorkOrderBoardQueryFilters.cs     |  5 +++
 2 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/Api.SeaHavenIndustries/Controllers/WorkOrderController.cs b/Api.SeaHavenIndustries/Controllers/WorkOrderController.cs
index f72501c..f3d5ca9 100644
--- a/Api.SeaHavenIndustries/Controllers/WorkOrderController.cs
+++ b/Api.SeaHavenIndustries/Controllers/WorkOrderController.cs
@@ -82,6 +82,12 @@ namespace Api.SeaHavenIndustries.Controllers
             _workOrderBoardService = workOrderBoardService;
         }
 
+        /// <summary>
+        /// Weekly board payload.
+        /// When <paramref name="myWorkOrders"/> is true, the authenticated user filter wins and
+        /// <paramref name="dispatchers"/> is ignored (not AND-combined).
+        /// Weekend WOs in a Mon–Sun window may have <c>dayGroup = null</c>; FE should handle that.
+        /// </summary>
         [HttpGet("board")]
         public async Task<IActionResult> GetBoard(
             [FromQuery, BindRequired] DateOnly weekStart,
@@ -96,21 +102,32 @@ namespace Api.SeaHavenIndustries.Controllers
             if (weekValidationError != null)
                 return BadRequest(weekValidationError);
 
-            var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
-            var query = new WorkOrderBoardQueryDto
+            try
             {
-                WeekStart = weekStart,
-                WeekEnd = weekEnd,
-                Dispatchers = dispatchers,
-                MyWorkOrders = myWorkOrders,
-                Types = types,
-                Search = search
-            };
+                var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
+                var query = new WorkOrderBoardQueryDto
+                {
+                    WeekStart = weekStart,
+                    WeekEnd = weekEnd,
+                    Dispatchers = dispatchers,
+                    MyWorkOrders = myWorkOrders,
+                    Types = types,
+                    Search = search
+                };
 
-            var result = await _workOrderBoardService.GetBoardAsync(query, userId);
-            return Ok(result);
+                var result = await _workOrderBoardService.GetBoardAsync(query, userId);
+                return Ok(result);
+            }
+            catch (ArgumentException ex)
+            {
+                return BadRequest(ex.Message);
+            }
         }
 
+        /// <summary>
+        /// Dispatcher dropdown options. Currently returns all non-deleted users
+        /// (role-filtered assignee list deferred until roles settle).
+        /// </summary>
         [HttpGet("lookups/dispatchers")]
         public async Task<IActionResult> GetDispatcherLookups()
         {
diff --git a/SeaHaven.DataServices/Helpers/WorkOrderBoardQueryFilters.cs b/SeaHaven.DataServices/Helpers/WorkOrderBoardQueryFilters.cs
index c57fc5f..d13b4d3 100644
--- a/SeaHaven.DataServices/Helpers/WorkOrderBoardQueryFilters.cs
+++ b/SeaHaven.DataServices/Helpers/WorkOrderBoardQueryFilters.cs
@@ -8,6 +8,11 @@ namespace SeaHaven.DataServices.Helpers
         public static IQueryable<WorkOrder> ApplyBaseScope(IQueryable<WorkOrder> query)
             => query.Where(w => w.istemplate != true && (w.IsDeleted != true || w.IsDeleted == null));
 
+        /// <summary>
+        /// Applies assignee filters. When <paramref name="myWorkOrders"/> is true and
+        /// <paramref name="currentUserId"/> is set, that takes precedence and
+        /// <paramref name="dispatchers"/> is ignored.
+        /// </summary>
         public static IQueryable<WorkOrder> ApplyDispatcherFilter(
             IQueryable<WorkOrder> query,
             IReadOnlyList<string>? dispatchers,