ADM-837：[docs] docs: spike about optimizing generate report backend logic

docs/src/content/docs/en/designs/optimize-generate-report.mdx

@@ -0,0 +1,203 @@
+---
+title: Optimize generate report
+description: solve issue about when one of the export button can not click but export metric button can click
+---
+
+# Context
+Considering to fix the issue about when one of the export button can not click but export metric button can click, and change logic about polling api in backend. we have to optimize generate report flow.
+
+# Design
+## C2 - Generate report - AS-IS
+
+### Sequence Diagram
+
+```plantuml
+@startuml report
+skin rose
+title C2 - Heartbeat - Generate Report - Transition
+participant Frontend
+participant Backend
+participant Jira
+participant Buildkite
+participant Github
+
+Frontend -> Backend: generate metrics for board related
+activate Backend
+Backend --> Frontend: response 202 with callback
+deactivate Backend
+
+group async process board related metrics
+    Backend -> Jira: get Jira raw data
+    activate Backend
+    activate Jira
+    Jira --> Backend: Jira raw 
+    deactivate Jira
+    Backend -> Backend: calculate metrics for velocity, cycle time and classification
+    Backend -> Backend: generate board report csv
+    deactivate Backend
+    note left
+        response.boardMetricsCompleted is true
+        board metrics are ready for display
+        board csv is ready for download
+    end note
+end
+
+Frontend -> Backend: generate metrics for pipeline,Source control(if required) related
+activate Backend
+Backend --> Frontend: response 202 with callback
+deactivate Backend
+
+group async process pipeline and sourcecontrol related metrics
+    Backend -> Buildkite: get Buildkite raw data
+    activate Backend
+    activate Buildkite
+    Buildkite --> Backend: Buildkite raw data
+    deactivate Buildkite
+    Backend -> Backend: calculate metrics for deployment frequency, \nchange failure rate and mean time to recovery
+    note left
+        pipeline metrics are ready for display
+    end note
+    opt if lead time for change required
+        Backend -> Github: get Github raw data
+        activate  Github
+        Github --> Backend: Github raw data
+        deactivate Github
+        Backend -> Backend: calculate metrics for lead time for change
+        note left
+            LTFC is ready for display
+        end note
+    end
+    Backend -> Backend: generate pipeline report csv with github data if required
+    note left
+        response.doraMetricsCompleted is true
+        pipeline report is ready for download
+    end note
+    deactivate Backend
+end
+
+loop until (response code is 201 and body.allMetricsReady==true) or (response code is 5xx) 
+    Frontend -> Backend: Polling the report
+    activate Backend
+    alt report is not ready
+        Backend --> Frontend: response 200
+    else report is ready
+        Backend --> Frontend: response 201 with report
+    else fail to process 
+        Backend --> Frontend: response 5xx
+    end
+    deactivate Backend
+end 
+@enduml
+```
+
+## C2 - Generate report - TO-BE
+### Sequence Diagram
+
+
+```plantuml
+@startuml report
+skin rose
+title C2 - Heartbeat - Generate Report - Transition
+participant Frontend
+participant Backend
+participant Jira
+participant Buildkite
+participant Github
+
+Frontend -> Backend: generate metrics for board or dora or both of them
+activate Backend
+Backend --> Frontend: response 202 with callback
+deactivate Backend
+
+
+Backend --> Backend: initialize reportStatus according to metricTypes list element
+activate Backend
+
+group async check if metricCsv can be generated 
+loop until (metricTypes list final element)
+
+    alt metricsType is Board
+        group async process board related metrics
+            Backend -> Jira: get Jira raw data，put this thread into thread list
+            activate Backend
+            activate Jira
+            Jira --> Backend: Jira raw 
+            deactivate Jira
+            Backend -> Backend: calculate metrics for velocity, cycle time and classification
+            Backend -> Backend: generate board report csv
+            deactivate Backend
+            note left
+                update response.boardMetricsCompleted as true
+                board metrics are ready for display
+                board csv is ready for download
+            end note
+        end
+
+
+    else metricsType is Dora
+        group async process pipeline and sourcecontrol related metrics
+            Backend -> Buildkite: get Buildkite raw data, put this thread into thread list
+            activate Backend
+            activate Buildkite
+            Buildkite --> Backend: Buildkite raw data
+            deactivate Buildkite
+            Backend -> Backend: calculate metrics for deployment frequency, change failure rate and mean time to recovery
+            note left
+                pipeline metrics are ready for display
+            end note
+            opt if lead time for change required
+                Backend -> Github: get Github raw data
+                activate  Github
+                Github --> Backend: Github raw data
+                deactivate Github
+                Backend -> Backend: calculate metrics for lead time for change
+                note left
+                    LTFC is ready for display
+                end note
+            end
+            Backend -> Backend: generate pipeline report csv with github data if required
+            note left
+                update response.doraMetricsCompleted as true
+                pipeline report is ready for download
+            end note
+            deactivate Backend
+        end
+    end
+
+     Backend --> Backend: wait for threadList element all execute completed
+     Backend --> Backend: generate metricCsv
+     note left
+     update allMetricsCompleted as true and write it on the file
+     end note
+end 
+    deactivate Backend
+end 
+
+loop until (response code is 201 and body.allMetricsCompleted==true) or (response code is 5xx) 
+    Frontend -> Backend: Polling the report
+    activate Backend
+    alt report is not ready
+        Backend --> Frontend: response 200
+    else report is ready
+        Backend --> Frontend: response 201 with report
+    else fail to process 
+        Backend --> Frontend: response 5xx
+    end
+    deactivate Backend
+end 
+@enduml
+```
+
+### API Design
+the request body of generate report api is the same as as-is, but will add one parameter in the request body.
+```
+URI: POST /reports
+Request payload:
+{
+   ...
+   "metricTypes": [
+        "string"
+      ]
+}
+```
+

docs/src/content/docs/en/spikes/tech-spikes-export-all-metrics-button-polling-api-backend-change.mdx

@@ -0,0 +1,62 @@
+---
+title: Tech solution of all metrics export button problems for ADM-822
+description: Tech solution of all metrics export button problems for ADM-822
+---
+
+## Background
+The front-end uses the allMetricsCompleted field of the back-end polling interface to determine whether the board and dora metric have been generated to determine whether the export metric button can be clicked. The backend's field judgment logic is determined based on the boardMetricsCompleted and doraMetricsCompleted fields, and the null value in both is ignored and compared. However, the following situations may lead to incorrect judgment, resulting in incorrect button display.
+See ADM-822 to get more information.
+
+### Wrong case 1
+The user selected board and dora. When generating indicators in the last step, if an error occurs and the board or dora request is not sent, you need to retry one or both of them. If only one of the requests (such as board) is successfully executed, That will cause boardMetricsCompleted=true, doraMetricsCompleted=null, ignoring the null value comparison, causing allMetricsCompleted to be true. At this time, the export metric button can be clicked, but the expectation is that the button cannot be clicked.
+
+### original fix in backend
+The backend modification is to change the way of allMetricsCompleted field judgment and change the null value to false by default before comparison. But the following problems will occur(wrong case 2).
+
+### Wrong case 2
+The user only selects board or dora. Finally, the indicator is generated, but the export metric button cannot be clicked. The reason is that the front end still determines whether it is clickable based on the allMetricsCompleted field. For example, if only board is selected, it will result in boardMetricsCompleted=true, doraMetricsCompleted=null, allMetricsCompleted=false
+
+### Temporary fix
+Frontend: The front end does not use allMetricsCompleted to determine the button status. Instead, it depends on whether borad or dora is currently selected. Look at boardMetricsComplete and doraMetricsCompleted to determine the button status.
+Backend: code revert
+
+### Frontend legacy issues
+The original problem of ADM-822 reappears
+
+### Backend legacy issues
+The logic of the allMetricsCompleted field in the backend remains the same, and there is still the problem of wrong case 1
+There is logic to generate all metric csv in the polling interface, which will be triggered when allMetricsCompleted=true, which will cause incomplete csv to be repeatedly generated in the polling interface in wrong case 1, affecting performance.
+The allMetricsCompleted field in the backend is currently no longer used by the frontend. Consider how to handle this field.
+
+### Why can’t it be purely back-end repaired?
+The backend cannot distinguish between the above wrong case 1 and wrong case 2. The backend cannot sense whether the user has selected board and dora, or only one of board and dora.
+
+
+## Expect
+1. When the user selects either board or dora and succeeds, the export metrics button can be displayed as clickable
+2. When the user selects both board and dora, the export metrics button can be displayed as expected by ADM-822
+
+
+## Solutions
+
+### For backend
+
+#### Modify generateReport Api
+1. Previous api is POST /reports/```{metricType}```, but now need to modify as POST /reports and add new Parameter metricTypesList in requestBody.
+2. Then write the metricTypes on file.
+3. According to the metricTypes to generate boardCsv or DoraCsv then we start another thread to check if boardCsv and DoraCsv are generated. if check pass, then we can generate metricCsv.
+
+#### Modify polling Api(POST /reports/```{reportId}```)
+1. to use metricTypesFile to check if allMetricsCompleted index is true by use the combination of boardMetricsCompleted index and doraMetricsCompleted index or just one of these two index. 
+2. remove generate metricCsv file in this api logic.
+
+#### Add a new scheduled task
+1. Delete expire metricTypes file regularly.
+
+### For Frontend
+
+1. revert to previous version's logic, still use allMetricsCompleted index to decide whether the button can click or not.
+2. modify the url and requestBody of generateReport Api。
+
+
+

docs/src/i18n/en/nav.ts

@@ -77,6 +77,11 @@ export default [
 		slug: 'designs/refinement-on-generate-report',
 		key: 'designs/refinement-on-generate-report',
 	},
+	{
+		text: 'Optimize generate report',
+		slug: 'designs/optimize-generate-report',
+		key: 'designs/optimize-generate-report',
+	},
 	{
 		text: 'Sequence diagrams',
 		slug: 'designs/sequence-diagrams',
@@ -161,6 +166,11 @@ export default [
 		slug: 'spikes/tech-spikes-calculate-rework-of-board-card',
 		key: 'spikes/tech-spikes-calculate-rework-of-board-card',
 	},
+	{
+		text: 'Solution to optimize generate report',
+		slug: 'spikes/tech-spikes-export-all-metrics-button-polling-api-backend-change',
+		key: 'spikes/tech-spikes-export-all-metrics-button-polling-api-backend-change',
+	},
 
 	{ text: 'Biz', header: true, type: 'biz', key: 'Biz' },
 	{ text: 'Biz context', slug: 'biz/business-context', key: 'biz/business-context' },