From 776d3830962cdddccebe3015b27bd03050ae04df Mon Sep 17 00:00:00 2001
From: Devadathan M B <devadathan.mb@fyle.in>
Date: Fri, 6 Dec 2024 00:27:36 +0530
Subject: [PATCH] feat: Add group_by_state support to advance request stats API

---
 src/components/schemas/advance_request.yaml | 85 ++++++++++++++++-----
 1 file changed, 68 insertions(+), 17 deletions(-)

diff --git a/src/components/schemas/advance_request.yaml b/src/components/schemas/advance_request.yaml
index 017a0eaf5..f82856761 100644
--- a/src/components/schemas/advance_request.yaml
+++ b/src/components/schemas/advance_request.yaml
@@ -149,29 +149,80 @@ advance_request_action_in:
       example: 'rpa21A2rdj2'
 
 advance_requests_stats_in:
+  type: object
+  required:
+    - data
   properties:
     query_params:
-      type: string
       description: | 
-        This field contains the query param string similar to the query params passed in advance_requests GET call for displaying advance_requests in the list view.
+        Query param string similar to advance_requests GET call. Use group_by_state=eq.true to get state-wise grouping of stats.
       nullable: false
-      example: id=in.('adr1263', 'adr1569')
+      example: id=in.('adr1263','adr1569')&group_by_state=eq.true
 
 advance_requests_stats_out:
-  type: object 
-  properties:
-    count:
-      type: integer
-      description: |
-        This field represents the total number of advance_requests that match the criteria specified in the query_params within the body of the request.
-      nullable: false
-      example: 1
-    total_amount:
-      allOf:
-        - $ref: './fields.yaml#/amount'
-      description: |
-        This field indicates the sum of amount of advance_requests that match the criteria specified in the query_params within the body of the request.
-      example: 100
+  type: array
+  description: |
+    Array containing stats objects. When group_by_state is true, contains objects for ALL possible states 
+    (with count and total_amount as 0 for states with no matching advance requests). When false or not provided, 
+    contains single object with aggregated stats and null state.
+  items:
+    type: object
+    required:
+      - count
+      - total_amount
+      - state
+    properties:
+      count:
+        type: integer
+        nullable: false
+        description: |
+          Number of advance requests that match the specified criteria.
+        example: 10
+      total_amount:
+        type: number
+        nullable: false
+        description: |
+          Sum of amounts for matching advance requests.
+        example: 44545.4
+      state:
+        type: string
+        nullable: true
+        description: |
+          Advance request state for grouping. null when group_by_state is false or not provided.
+          When group_by_state is true, response includes all possible states, with count=0 
+          and total_amount=0 for states with no matching advance requests.
+        example: DRAFT
+        enum:
+          - DRAFT
+          - APPROVAL_PENDING
+          - APPROVED
+          - SENT_BACK
+          - PULLED_BACK
+          - REJECTED
+          - PAID
+          - null
+  example:
+    - state: "DRAFT"
+      count: 10
+      total_amount: 44545.4
+    - state: "APPROVAL_PENDING"
+      count: 0
+      total_amount: 0
+    - state: "APPROVED"
+      count: 343
+      total_amount: 1337.0
+    - state: "SENT_BACK"
+      count: 0
+      total_amount: 0
+    - state: "PULLED_BACK"
+      count: 0
+      total_amount: 0
+    - state: "REJECTED"
+      count: 0
+      total_amount: 0
+    - state: "PAID"
+      count: 0
+      total_amount: 0
 
 advance_request_out_embed:
   type: object