[Feature] add version optimistic locking for the Competition Hierarchy (#545)

* feat: add version field to CompetitionEvent

* feat(db): add migrations

* feat: add method to GlobalExceptionHandler that handle OptimisticLockingFailureException

* feat: add check to HierarchyValidator

* feat: update DTOs

* feat: add StaleEntityVersionException & ErrorCode.ENTITY_VERSION_CONFLICT

* feat: add/update unit tests

* fix: unit test

* fix: unit test

* chore: fix formatter

* fix git error

* fix: avoid exposing the fully qualified entity class name

* feat: add OpenApi docs about 409 error

* feat: add/update Javadocs in services in competition module

* fix formatter

Author: antonpampukha

src/main/java/com/itasocialacademy/oitassist/competition/controller/CompetitionController.java

@@ -143,13 +143,17 @@ public ResponseEntity<CompetitionTreeResponse> getCompetitionTree(@PathVariable
         @ApiResponse(responseCode = "403", description = "Access denied (requires ADMIN or ORG role)",
             content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class))),
         @ApiResponse(responseCode = "404", description = "Competition not found",
+            content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class))),
+        @ApiResponse(responseCode = "409",
+            description = "Conflict — the entity was modified by another request since it was last read "
+                + "(stale version)",
             content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)))
     })
     @PatchMapping("/{competitionId}/status")
     @PreAuthorize("hasAnyRole('ADMIN', 'ORG')")
     public ResponseEntity<CompetitionResponse> changeStatus(
         @PathVariable Long competitionId,
         @Valid @RequestBody ChangeCompetitionStatusRequest request) {
-        return ResponseEntity.ok(competitionService.changeStatus(competitionId, request.status()));
+        return ResponseEntity.ok(competitionService.changeStatus(competitionId, request));
     }
 }

src/main/java/com/itasocialacademy/oitassist/competition/controller/StageController.java

@@ -84,6 +84,10 @@ public ResponseEntity<List<StageResponse>> getAllStages(@PathVariable Long compe
         @ApiResponse(responseCode = "403", description = "Access denied",
             content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class))),
         @ApiResponse(responseCode = "404", description = "Stage not found",
+            content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class))),
+        @ApiResponse(responseCode = "409",
+            description = "Conflict — the entity was modified by another request since it was last read "
+                + "(stale version)",
             content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)))
     })
     @PutMapping("/competitions/{competitionId}/stages/{stageId}")
@@ -105,6 +109,10 @@ public ResponseEntity<StageResponse> updateStage(
         @ApiResponse(responseCode = "403", description = "Access denied",
             content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class))),
         @ApiResponse(responseCode = "404", description = "Stage not found",
+            content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class))),
+        @ApiResponse(responseCode = "409",
+            description = "Conflict — the entity was modified by another request since it was last read "
+                + "(stale version)",
             content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)))
     })
     @PreAuthorize("hasAnyRole('ADMIN', 'ORG')")

src/main/java/com/itasocialacademy/oitassist/competition/controller/TourController.java

@@ -79,7 +79,11 @@ public ResponseEntity<List<TourResponse>> getAllTours(@PathVariable Long stageId
         @ApiResponse(responseCode = "403", description = "Access denied",
             content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
         @ApiResponse(responseCode = "404", description = "Tour not found",
-            content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
+            content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+        @ApiResponse(responseCode = "409",
+            description = "Conflict — the entity was modified by another request since it was last read "
+                + "(stale version)",
+            content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)))
     })
     @PutMapping("/stages/{stageId}/tours/{tourId}")
     @PreAuthorize("hasAnyRole('ADMIN', 'ORG')")
@@ -98,7 +102,11 @@ public ResponseEntity<TourResponse> updateTour(
         @ApiResponse(responseCode = "403", description = "Access denied",
             content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class))),
         @ApiResponse(responseCode = "404", description = "Tour not found",
-            content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
+            content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
+        @ApiResponse(responseCode = "409",
+            description = "Conflict — the entity was modified by another request since it was last read "
+                + "(stale version)",
+            content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)))
     })
     @PatchMapping("/stages/{stageId}/tours/{tourId}/status")
     @PreAuthorize("hasAnyRole('ADMIN', 'ORG')")

src/main/java/com/itasocialacademy/oitassist/competition/dao/model/CompetitionEvent.java

@@ -6,6 +6,7 @@
 import jakarta.persistence.GenerationType;
 import jakarta.persistence.Id;
 import jakarta.persistence.MappedSuperclass;
+import jakarta.persistence.Version;
 import java.time.Instant;
 import java.time.ZonedDateTime;
 import lombok.AllArgsConstructor;
@@ -58,4 +59,8 @@ public abstract class CompetitionEvent {
     @LastModifiedDate
     @Column(name = "updated_at")
     private Instant updatedAt;
+
+    @Version
+    @Column(name = "version", nullable = false)
+    private Long version;
 }

src/main/java/com/itasocialacademy/oitassist/competition/dto/request/ChangeCompetitionStatusRequest.java

@@ -2,6 +2,7 @@
 
 import com.itasocialacademy.oitassist.competition.dao.enums.CompetitionStatus;
 import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
 import jakarta.validation.constraints.NotNull;
 
 @Schema(description = "DTO for changing the lifecycle status of a Competition")
@@ -10,5 +11,8 @@ public record ChangeCompetitionStatusRequest(
         description = "The target status to transition the competition into (e.g., PUBLISHED, FINISHED, ARCHIVED)",
         example = "PUBLISHED",
         requiredMode = Schema.RequiredMode.REQUIRED) @NotNull(
-            message = "New status cannot be null") CompetitionStatus status) {
+            message = "New status cannot be null") CompetitionStatus status,
+
+    @Schema(description = "Optimistic locking version; must be echoed back on updates",
+        requiredMode = RequiredMode.REQUIRED) @NotNull Long version) {
 }

src/main/java/com/itasocialacademy/oitassist/competition/dto/request/ChangeStageStatusRequest.java

@@ -2,11 +2,15 @@
 
 import com.itasocialacademy.oitassist.competition.dao.enums.StageStatus;
 import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
 import jakarta.validation.constraints.NotNull;
 
 @Schema(description = "DTO for changing the lifecycle status of a Stage")
 public record ChangeStageStatusRequest(
     @Schema(description = "The new status of the stage", example = "IN_PROGRESS",
         requiredMode = Schema.RequiredMode.REQUIRED) @NotNull(
-            message = "Stage status must not be null") StageStatus status) {
+            message = "Stage status must not be null") StageStatus status,
+
+    @Schema(description = "Optimistic locking version; must be echoed back on updates",
+        requiredMode = RequiredMode.REQUIRED) @NotNull Long version) {
 }

src/main/java/com/itasocialacademy/oitassist/competition/dto/request/ChangeTourStatusRequest.java

@@ -2,11 +2,15 @@
 
 import com.itasocialacademy.oitassist.competition.dao.enums.ExecutionStatus;
 import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
 import jakarta.validation.constraints.NotNull;
 
 @Schema(description = "DTO for changing the lifecycle status of a Tour")
 public record ChangeTourStatusRequest(
     @Schema(description = "The new execution status of the tour", example = "IN_PROGRESS",
         requiredMode = Schema.RequiredMode.REQUIRED) @NotNull(
-            message = "Execution status must not be null") ExecutionStatus status) {
+            message = "Execution status must not be null") ExecutionStatus status,
+
+    @Schema(description = "Optimistic locking version; must be echoed back on updates",
+        requiredMode = RequiredMode.REQUIRED) @NotNull Long version) {
 }

src/main/java/com/itasocialacademy/oitassist/competition/dto/request/UpdateStageRequest.java

@@ -4,6 +4,7 @@
 import com.itasocialacademy.oitassist.competition.dto.validation.ValidDateRange;
 import com.itasocialacademy.oitassist.competition.dao.enums.StageScope;
 import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;
@@ -26,6 +27,9 @@ public record UpdateStageRequest(
     @Schema(description = "Scope of the stage", example = "NATIONAL",
         requiredMode = Schema.RequiredMode.REQUIRED) @NotNull StageScope scope,
 
-    @Schema(description = "Order of the stage in the hierarchy", example = "2") @Min(1) Short sortPosition)
+    @Schema(description = "Order of the stage in the hierarchy", example = "2") @Min(1) Short sortPosition,
+
+    @Schema(description = "Optimistic locking version; must be echoed back on updates",
+        requiredMode = RequiredMode.REQUIRED) @NotNull Long version)
     implements HasDateRange {
 }

src/main/java/com/itasocialacademy/oitassist/competition/dto/request/UpdateTourRequest.java

@@ -3,6 +3,7 @@
 import com.itasocialacademy.oitassist.competition.dto.validation.HasDateRange;
 import com.itasocialacademy.oitassist.competition.dto.validation.ValidDateRange;
 import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;
@@ -25,6 +26,10 @@ public record UpdateTourRequest(
     @Schema(description = "Location for the tour", example = "Konotop city",
         requiredMode = Schema.RequiredMode.REQUIRED) @NotBlank String location,
 
-    @Schema(description = "Order of the tour in the hierarchy", example = "1") @Min(1) Short sortPosition)
+    @Schema(description = "Order of the tour in the hierarchy", example = "1") @Min(1) Short sortPosition,
+
+    @Schema(description = "Optimistic locking version; must be echoed back on updates",
+        requiredMode = RequiredMode.REQUIRED) @NotNull Long version)
+
     implements HasDateRange {
 }

src/main/java/com/itasocialacademy/oitassist/competition/dto/response/CompetitionResponse.java

@@ -15,5 +15,6 @@ public record CompetitionResponse(
     @Schema(description = "End date", example = "2026-12-25T18:00:00Z") ZonedDateTime dateFinish,
     @Schema(description = "Current lifecycle status", example = "PUBLISHED") CompetitionStatus competitionStatus,
     @Schema(description = "ID of the user who created it", example = "5") Long createdBy,
-    @Schema(description = "ID of the user who last updated it", example = "5") Long updatedBy) {
+    @Schema(description = "ID of the user who last updated it", example = "5") Long updatedBy,
+    @Schema(description = "Optimistic locking version; must be echoed back on updates") Long version) {
 }