Enhance goal progress schema by adding year and to-date calculations, and improve descriptions for clarity

openapi.yaml

@@ -8414,7 +8414,9 @@ components:
     DepartmentGoalProgress:
       type: object
       title: Department progress details
-      description: Goal progress details for a single department across multiple timeframes
+      description: |
+        Goal progress details for a single department across multiple timeframes.
+        Timeframes are clamped to the goal timeframe (never before goal start and never after goal end).
       properties:
         all:
           $ref: '#/components/schemas/GoalProgressDetails'
@@ -8424,6 +8426,10 @@ components:
           $ref: '#/components/schemas/GoalProgressDetails'
         month:
           $ref: '#/components/schemas/GoalProgressDetails'
+        year:
+          $ref: '#/components/schemas/GoalProgressDetails'
+        to_date:
+          $ref: '#/components/schemas/GoalProgressDetails'
 
     DepartmentGoal:
       type: object
@@ -8440,7 +8446,10 @@ components:
           $ref: '#/components/schemas/GoalsCriteria'
         progress:
           type: object
-          description: Goal progress details for various timeframes
+          description: |
+            Goal progress details for various timeframes.
+            `year` starts at January 1 of the current year or the goal start, whichever is later.
+            `to_date` starts at the goal start and ends at today (also clamped by goal end).
           properties:
             all:
               $ref: '#/components/schemas/GoalProgressDetails'
@@ -8450,9 +8459,15 @@ components:
               $ref: '#/components/schemas/GoalProgressDetails'
             month:
               $ref: '#/components/schemas/GoalProgressDetails'
+            year:
+              $ref: '#/components/schemas/GoalProgressDetails'
+            to_date:
+              $ref: '#/components/schemas/GoalProgressDetails'
             departmental_distribution:
               type: object
-              description: Progress details broken down by department. Keys are department IDs.
+              description: |
+                Progress details broken down by department. Keys are department IDs.
+                Includes `all`, `today`, `week`, `month`, `year`, and `to_date` timeframes.
               x-additionalPropertiesName: department_id
               additionalProperties:
                 $ref: '#/components/schemas/DepartmentGoalProgress'
@@ -8470,6 +8485,12 @@ components:
                   month:
                     count: 15
                     target: 100
+                  year:
+                    count: 15
+                    target: 100
+                  to_date:
+                    count: 15
+                    target: 100
         created_at:
           type: string
           description: Creation timestamp