Enhance department weather timeline API: support multiple IDs, add timeline date override, improve ID parsing, update schema examples, and expand related tests.

openapi.yaml

@@ -3268,7 +3268,7 @@ paths:
       parameters:
         - name: id
           in: query
-          required: false
+          required: true
           schema:
             type: integer
         - $ref: '#/components/parameters/PageParam'
@@ -7798,31 +7798,63 @@ paths:
       tags:
         - Departments
       summary: Get department weather timeline
-      description: Returns hourly weather, washes, hours and productivity status for a department
+      description: Returns 48 hourly entries with weather, washes, Workfeed employee-hours, and productivity status aggregated across selected departments (server local time). Default range is start of yesterday (`00:00`) to end of today (`23:00`). Use `date` (`YYYY-MM-DD`) to override the anchor day and get start of previous day to end of selected day.
       operationId: getDepartmentWeatherTimeline
       parameters:
         - name: id
           in: query
-          required: true
+          required: false
           schema:
-            type: integer
-            minimum: 1
-          description: Department ID
+            type: array
+            items:
+              type: integer
+              minimum: 1
+            minItems: 1
+            uniqueItems: true
+          style: form
+          explode: true
+          description: Department ID list. Repeat `id` to select multiple departments (`?id=1&id=2`).
+        - name: ids
+          in: query
+          required: false
+          schema:
+            type: string
+            example: '1,2,3'
+          description: Optional CSV alternative for department IDs. Merged with `id` if both are provided. At least one of `id` or `ids` must be provided.
+        - name: date
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date
+            example: '2026-03-24'
+          description: Optional date override (`YYYY-MM-DD`). Range becomes start of previous day to end of this date.
       responses:
         '200':
           description: Department weather timeline retrieved successfully
           content:
             application/json:
               schema:
-                allOf:
-                  - $ref: '#/components/schemas/SuccessResponse'
-                  - type: object
-                    properties:
-                      data:
-                        type: array
-                        items:
-                          $ref: '#/components/schemas/DepartmentWeatherTimelineEntry'
                 $ref: '#/components/schemas/DepartmentWeatherTimelineResponse'
+              example:
+                success: true
+                meta: []
+                includes: []
+                data:
+                  - date: '2026-03-23'
+                    time: '00:00'
+                    current: false
+                    weather: mostly_cloudy
+                    washes: 1
+                    hours: 2.0
+                    status: degraded
+                  - date: '2026-03-24'
+                    time: '13:00'
+                    current: true
+                    weather: rain
+                    washes: 0
+                    hours: 2.5
+                    status: unhealthy
 
   /modules/entra/users:
     get:
@@ -10424,9 +10456,19 @@ components:
     DepartmentWeatherTimelineEntry:
       type: object
       properties:
+        date:
+          type: string
+          format: date
+          description: Calendar date for the hourly slot (`YYYY-MM-DD`).
+          example: '2026-03-24'
         time:
           type: string
+          description: Hour label for the slot in 24-hour format (`HH:00`).
           example: '01:00'
+        current:
+          type: boolean
+          description: True when this slot matches the current server hour.
+          example: false
         weather:
           $ref: '#/components/schemas/DepartmentWeatherCondition'
         washes:
@@ -10434,12 +10476,14 @@ components:
           minimum: 0
           example: 0
         hours:
-          type: integer
+          type: number
+          format: float
           minimum: 0
-          example: 10
+          example: 2.5
+          description: Sum of Workfeed employee-hours in the department for this exact hour slot
         status:
           $ref: '#/components/schemas/DepartmentWeatherStatus'
-      required: [time, weather, washes, hours, status]
+      required: [date, time, current, weather, washes, hours, status]
 
     WeatherApiObjectResponse:
       allOf:
@@ -10607,6 +10651,9 @@ components:
           properties:
             data:
               type: array
+              minItems: 48
+              maxItems: 48
+              description: 48 contiguous hourly slots from start of previous day (`00:00`) to end of anchor day (`23:00`). Anchor day is today unless `date` is provided.
               items:
                 $ref: '#/components/schemas/DepartmentWeatherTimelineEntry'
           required: [data]