INC-1265: Add api endpoint that deactivates all incentive levels in a prison (#453)

* Add api endpoint that deactivates all incentive levels in a prison which is needed when a prison is closed
* Nest incentive level tests deeper so that test cases for the same endpoint are grouped together
* Audit & notify about _changed_ prison incentive levels when a whole prison is deactivated rather than all levels. The endpoint still returns all levels.

Author: ushkarev

doc/architecture/decisions/0004-reference-data-sync.md

@@ -431,6 +431,10 @@ Authorised requests will require roles with write scope.
 }
 ```
 
+#### Deactivate all levels in a prison
+
+`DELETE /incentive/prison-levels/{prisonId}`
+
 #### Deactivate a level in a prison
 
 `DELETE /incentive/prison-levels/{prisonId}/level/{levelCode}`

src/main/kotlin/uk/gov/justice/digital/hmpps/incentivesapi/resource/PrisonIncentiveLevelResource.kt

@@ -243,6 +243,46 @@ class PrisonIncentiveLevelResource(
       ?: throw NoDataWithCodeFoundException("incentive level", levelCode)
   }
 
+  @DeleteMapping("{prisonId}")
+  @PreAuthorize("hasRole('MAINTAIN_PRISON_IEP_LEVELS') and hasAuthority('SCOPE_write')")
+  @Operation(
+    summary = "Deactivate all incentive levels for a prison",
+    description = "This can be used when a prison closes. " +
+      "Returns all incentive levels in this prison include those that were already inactive. " +
+      "Deactivating a level is only possible if there are no prisoners currently on it." +
+      "\n\nRequires role: MAINTAIN_PRISON_IEP_LEVELS with write scope" +
+      "\n\nRaises HMPPS domain event: \"incentives.prison-level.changed\"",
+    responses = [
+      ApiResponse(
+        responseCode = "200",
+        description = "Prison incentive levels deactivated",
+      ),
+      ApiResponse(
+        responseCode = "400",
+        description = "There are prisoners on some incentive level at this prison",
+        content = [Content(mediaType = "application/json", schema = Schema(implementation = ErrorResponse::class))],
+      ),
+      ApiResponse(
+        responseCode = "401",
+        description = "Unauthorized to access this endpoint",
+        content = [Content(mediaType = "application/json", schema = Schema(implementation = ErrorResponse::class))],
+      ),
+      ApiResponse(
+        responseCode = "403",
+        description = "Incorrect permissions to use this endpoint",
+        content = [Content(mediaType = "application/json", schema = Schema(implementation = ErrorResponse::class))],
+      ),
+    ],
+  )
+  suspend fun deactivateAllPrisonIncentiveLevels(
+    @Schema(description = "Prison id", example = "MDI", required = true, minLength = 3, maxLength = 6)
+    @PathVariable
+    prisonId: String,
+  ): List<PrisonIncentiveLevel> {
+    prisonIncentiveLevelService.deactivateAllPrisonIncentiveLevels(prisonId)
+    return prisonIncentiveLevelService.getAllPrisonIncentiveLevels(prisonId)
+  }
+
   @DeleteMapping("{prisonId}/level/{levelCode}")
   @PreAuthorize("hasRole('MAINTAIN_PRISON_IEP_LEVELS') and hasAuthority('SCOPE_write')")
   @Operation(

src/main/kotlin/uk/gov/justice/digital/hmpps/incentivesapi/service/PrisonIncentiveLevelAuditedService.kt

@@ -38,6 +38,13 @@ class PrisonIncentiveLevelAuditedService(
       }
   }
 
+  override suspend fun deactivateAllPrisonIncentiveLevels(prisonId: String): List<PrisonIncentiveLevelDTO> {
+    return super.deactivateAllPrisonIncentiveLevels(prisonId)
+      .onEach {
+        auditAndPublishPrisonLevelChangeEvent(it)
+      }
+  }
+
   private suspend fun auditAndPublishPrisonLevelChangeEvent(prisonIncentiveLevel: PrisonIncentiveLevelDTO) {
     auditService.sendMessage(
       AuditType.PRISON_INCENTIVE_LEVEL_UPDATED,

src/main/kotlin/uk/gov/justice/digital/hmpps/incentivesapi/service/PrisonIncentiveLevelService.kt

@@ -2,6 +2,7 @@ package uk.gov.justice.digital.hmpps.incentivesapi.service
 
 import jakarta.validation.ValidationException
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.collect
 import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.flow.toList
 import org.springframework.stereotype.Service
@@ -167,6 +168,31 @@ class PrisonIncentiveLevelService(
     }
   }
 
+  /**
+   * Deactivate all incentive levels for a given prison; useful for when prisons are closed.
+   * NB: returns only the incentive levels that were deactivated
+   */
+  @Transactional
+  suspend fun deactivateAllPrisonIncentiveLevels(prisonId: String): List<PrisonIncentiveLevelDTO> {
+    val prisonIncentiveLevels = prisonIncentiveLevelRepository.findAllByPrisonId(prisonId).toList()
+    val prisonIncentiveLevelsWithPrisoners = prisonIncentiveLevels.filter { prisonIncentiveLevel ->
+      countPrisonersService.prisonersExistOnLevelInPrison(prisonId, prisonIncentiveLevel.levelCode)
+    }
+    if (prisonIncentiveLevelsWithPrisoners.isNotEmpty()) {
+      throw ValidationExceptionWithErrorCode(
+        "A level must remain active if there are prisoners on it currently",
+        ErrorCode.PrisonIncentiveLevelActiveIfPrisonersExist,
+        moreInfo = prisonIncentiveLevelsWithPrisoners.map(PrisonIncentiveLevel::levelCode).joinToString(","),
+      )
+    }
+    return prisonIncentiveLevelRepository.saveAll(
+      prisonIncentiveLevels.filter(PrisonIncentiveLevel::active)
+        .map { prisonIncentiveLevel ->
+          prisonIncentiveLevel.withUpdate(PrisonIncentiveLevelUpdateDTO(active = false))
+        },
+    ).toListOfDTO()
+  }
+
   private fun PrisonIncentiveLevel.withUpdate(update: PrisonIncentiveLevelUpdateDTO): PrisonIncentiveLevel = copy(
     active = update.active ?: active,
     defaultOnAdmission = update.defaultOnAdmission ?: defaultOnAdmission,