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.

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);
+            try
-            var query = new WorkOrderBoardQueryDto
             {
-                WeekStart = weekStart,
+                var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
-                WeekEnd = weekEnd,
+                var query = new WorkOrderBoardQueryDto
-                Dispatchers = dispatchers,
+                {
-                MyWorkOrders = myWorkOrders,
+                    WeekStart = weekStart,
-                Types = types,
+                    WeekEnd = weekEnd,
-                Search = search
+                    Dispatchers = dispatchers,
-            };
+                    MyWorkOrders = myWorkOrders,
+                    Types = types,
+                    Search = search
+                };
 
-            var result = await _workOrderBoardService.GetBoardAsync(query, userId);
+                var result = await _workOrderBoardService.GetBoardAsync(query, userId);
-            return Ok(result);
+                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()
         {

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,