Merge pull request #313 from pagopa/PPANTT-46-add-maintenance-summary…

…-api

[PPANTT-46] feat: Add maintenance summary API

openapi/openapi.json

@@ -1201,7 +1201,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Created",
+            "description": "OK",
             "headers": {
               "X-Request-Id": {
                 "description": "This header identifies the call",
@@ -1451,6 +1451,163 @@
         }
       ]
     },
+    "/brokers/{brokercode}/station-maintenances/summary": {
+      "get": {
+        "tags": [
+          "Creditor Institutions"
+        ],
+        "summary": "Get the hours' summary of stations' maintenance for the specified broker",
+        "operationId": "getBrokerMaintenancesSummary",
+        "parameters": [
+          {
+            "name": "brokercode",
+            "in": "path",
+            "description": "Broker's tax code",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "maintenanceYear",
+            "in": "query",
+            "description": "Year of maintenance (yyyy)",
+            "required": true,
+            "schema": {
+              "maxLength": 4,
+              "minLength": 4,
+              "type": "string"
+            },
+            "example": 2024
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "headers": {
+              "X-Request-Id": {
+                "description": "This header identifies the call",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MaintenanceHoursSummaryResource"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "headers": {
+              "X-Request-Id": {
+                "description": "This header identifies the call",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemJson"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized",
+            "headers": {
+              "X-Request-Id": {
+                "description": "This header identifies the call",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden",
+            "headers": {
+              "X-Request-Id": {
+                "description": "This header identifies the call",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "headers": {
+              "X-Request-Id": {
+                "description": "This header identifies the call",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemJson"
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Too many requests",
+            "headers": {
+              "X-Request-Id": {
+                "description": "This header identifies the call",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Service unavailable",
+            "headers": {
+              "X-Request-Id": {
+                "description": "This header identifies the call",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemJson"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "ApiKey": []
+          },
+          {
+            "Authorization": []
+          }
+        ]
+      },
+      "parameters": [
+        {
+          "name": "X-Request-Id",
+          "in": "header",
+          "description": "This header identifies the call, if not passed it is self-generated. This ID is returned in the response.",
+          "schema": {
+            "type": "string"
+          }
+        }
+      ]
+    },
     "/brokers/{brokercode}/station-maintenances/{maintenanceid}": {
       "put": {
         "tags": [
@@ -1491,7 +1648,7 @@
         },
         "responses": {
           "200": {
-            "description": "Created",
+            "description": "OK",
             "headers": {
               "X-Request-Id": {
                 "description": "This header identifies the call",
@@ -20490,6 +20647,38 @@
             "$ref": "#/components/schemas/PageInfo"
           }
         }
+      },
+      "MaintenanceHoursSummaryResource": {
+        "required": [
+          "annual_hours_limit",
+          "extra_hours",
+          "remaining_hours",
+          "scheduled_hours",
+          "used_hours"
+        ],
+        "type": "object",
+        "properties": {
+          "used_hours": {
+            "type": "string",
+            "description": "Count of used maintenance's hours"
+          },
+          "scheduled_hours": {
+            "type": "string",
+            "description": "Count of scheduled maintenance's hours"
+          },
+          "remaining_hours": {
+            "type": "string",
+            "description": "Count of remaining maintenance's hours before annual limit"
+          },
+          "extra_hours": {
+            "type": "string",
+            "description": "Count of maintenance's hours that exceed annual limit"
+          },
+          "annual_hours_limit": {
+            "type": "string",
+            "description": "Annual limit of maintenance hours"
+          }
+        }
       }
     },
     "securitySchemes": {

src/main/java/it/gov/pagopa/apiconfig/core/controller/StationMaintenanceController.java

@@ -10,6 +10,7 @@
 import io.swagger.v3.oas.annotations.tags.Tag;
 import it.gov.pagopa.apiconfig.core.model.ProblemJson;
 import it.gov.pagopa.apiconfig.core.model.stationmaintenance.CreateStationMaintenance;
+import it.gov.pagopa.apiconfig.core.model.stationmaintenance.MaintenanceHoursSummaryResource;
 import it.gov.pagopa.apiconfig.core.model.stationmaintenance.StationMaintenanceListResource;
 import it.gov.pagopa.apiconfig.core.model.stationmaintenance.StationMaintenanceResource;
 import it.gov.pagopa.apiconfig.core.model.stationmaintenance.UpdateStationMaintenance;
@@ -35,6 +36,7 @@
 import javax.validation.constraints.NotNull;
 import javax.validation.constraints.Positive;
 import javax.validation.constraints.PositiveOrZero;
+import javax.validation.constraints.Size;
 import java.time.OffsetDateTime;
 
 @RestController
@@ -53,7 +55,7 @@ public StationMaintenanceController(StationMaintenanceService stationMaintenance
     @Operation(summary = "Get a paginated list of station's maintenance for the specified broker",
             security = {@SecurityRequirement(name = "ApiKey"), @SecurityRequirement(name = "Authorization")})
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "Created",
+            @ApiResponse(responseCode = "200", description = "OK",
                     content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = StationMaintenanceListResource.class))),
             @ApiResponse(responseCode = "400", description = "Bad Request",
                     content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = ProblemJson.class))),
@@ -118,7 +120,7 @@ public ResponseEntity<StationMaintenanceResource> createStationMaintenance(
     @Operation(summary = "Update a maintenance for the specified station",
             security = {@SecurityRequirement(name = "ApiKey"), @SecurityRequirement(name = "Authorization")})
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "Created",
+            @ApiResponse(responseCode = "200", description = "OK",
                     content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = StationMaintenanceResource.class))),
             @ApiResponse(responseCode = "400", description = "Bad Request",
                     content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = ProblemJson.class))),
@@ -141,4 +143,27 @@ public ResponseEntity<StationMaintenanceResource> updateStationMaintenance(
                         updateStationMaintenance(brokerCode, maintenanceId, updateStationMaintenance)
         );
     }
+
+    @Operation(summary = "Get the hours' summary of stations' maintenance for the specified broker",
+            security = {@SecurityRequirement(name = "ApiKey"), @SecurityRequirement(name = "Authorization")})
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "OK",
+                    content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = MaintenanceHoursSummaryResource.class))),
+            @ApiResponse(responseCode = "400", description = "Bad Request",
+                    content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = ProblemJson.class))),
+            @ApiResponse(responseCode = "401", description = "Unauthorized", content = @Content(schema = @Schema())),
+            @ApiResponse(responseCode = "403", description = "Forbidden", content = @Content(schema = @Schema())),
+            @ApiResponse(responseCode = "404", description = "Not Found",
+                    content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = ProblemJson.class))),
+            @ApiResponse(responseCode = "429", description = "Too many requests", content = @Content(schema = @Schema())),
+            @ApiResponse(responseCode = "500", description = "Service unavailable",
+                    content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = ProblemJson.class)))
+    })
+    @GetMapping(value = "/{brokercode}/station-maintenances/summary", produces = {MediaType.APPLICATION_JSON_VALUE})
+    public ResponseEntity<MaintenanceHoursSummaryResource> getBrokerMaintenancesSummary(
+            @Parameter(description = "Broker's tax code") @PathVariable("brokercode") String brokerCode,
+            @Parameter(description = "Year of maintenance (yyyy)", example = "2024") @RequestParam @Size(min = 4, max = 4) String maintenanceYear
+    ) {
+        return ResponseEntity.ok(this.stationMaintenanceService.getBrokerMaintenancesSummary(brokerCode, maintenanceYear));
+    }
 }

src/main/java/it/gov/pagopa/apiconfig/core/model/stationmaintenance/MaintenanceHoursSummaryResource.java

@@ -0,0 +1,47 @@
+package it.gov.pagopa.apiconfig.core.model.stationmaintenance;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import javax.validation.constraints.NotNull;
+
+/**
+ * Model class that hold the hours' summary of stations' maintenance for a specific broker
+ */
+@Getter
+@Setter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class MaintenanceHoursSummaryResource {
+
+    @JsonProperty("used_hours")
+    @Schema(description = "Count of used maintenance's hours", required = true)
+    @NotNull
+    private String usedHours;
+
+    @JsonProperty("scheduled_hours")
+    @Schema(description = "Count of scheduled maintenance's hours", required = true)
+    @NotNull
+    private String scheduledHours;
+
+    @JsonProperty("remaining_hours")
+    @Schema(description = "Count of remaining maintenance's hours before annual limit", required = true)
+    @NotNull
+    private String remainingHours;
+
+    @JsonProperty("extra_hours")
+    @Schema(description = "Count of maintenance's hours that exceed annual limit", required = true)
+    @NotNull
+    private String extraHours;
+
+    @JsonProperty("annual_hours_limit")
+    @Schema(description = "Annual limit of maintenance hours", required = true)
+    @NotNull
+    private String annualHoursLimit;
+}

src/main/java/it/gov/pagopa/apiconfig/core/model/stationmaintenance/StationMaintenanceResource.java

@@ -17,7 +17,7 @@
 import java.time.OffsetDateTime;
 
 /**
- * Model class the response for station's maintenance APIs
+ * Model class of the response for station's maintenance APIs
  */
 @Getter
 @Setter