[Feature] add version optimistic locking for the Competition Hierarchy

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

@@ -150,6 +150,6 @@ public ResponseEntity<CompetitionTreeResponse> getCompetitionTree(@PathVariable
     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/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) {
 }

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

@@ -2,9 +2,11 @@
 
 import com.itasocialacademy.oitassist.competition.dao.enums.StageScope;
 import com.itasocialacademy.oitassist.competition.dao.enums.StageStatus;
+import io.swagger.v3.oas.annotations.media.Schema;
 import java.time.ZonedDateTime;
 import lombok.Builder;
 
+@Schema(description = "DTO representing a Stage entity response")
 @Builder
 public record StageResponse(
     Long id,
@@ -15,5 +17,6 @@ public record StageResponse(
     ZonedDateTime dateFinish,
     Short sortPosition,
     StageScope scope,
-    StageStatus status) {
+    StageStatus status,
+    Long version) {
 }

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

@@ -14,5 +14,6 @@ public record TourResponse(
     ZonedDateTime dateFinish,
     Short sortPosition,
     String location,
-    ExecutionStatus executionStatus) {
+    ExecutionStatus executionStatus,
+    Long version) {
 }

src/main/java/com/itasocialacademy/oitassist/competition/exceptions/StaleEntityVersionException.java

@@ -0,0 +1,19 @@
+package com.itasocialacademy.oitassist.competition.exceptions;
+
+import com.itasocialacademy.oitassist.core.enums.ErrorCode;
+import com.itasocialacademy.oitassist.core.exceptions.BusinessException;
+
+/**
+ * Thrown when a client-submitted {@code version} does not match the entity's
+ * current version in the database — i.e. the entity was modified by someone
+ * else since the client last read it.
+ */
+public class StaleEntityVersionException extends BusinessException {
+    public static final String ERROR_MESSAGE =
+        "Object of class [%s] with identifier [%s] was updated by another request.";
+
+    public StaleEntityVersionException(Class<?> entityClass, Object identifier) {
+        super(ERROR_MESSAGE
+            .formatted(entityClass.getName(), identifier), ErrorCode.ENTITY_VERSION_CONFLICT);
+    }
+}

src/main/java/com/itasocialacademy/oitassist/competition/service/CompetitionServiceImpl.java

@@ -9,6 +9,7 @@
 import com.itasocialacademy.oitassist.competition.dao.repository.TourRepository;
 import com.itasocialacademy.oitassist.competition.dao.specification.CompetitionSpecification;
 import com.itasocialacademy.oitassist.competition.dto.filter.CompetitionSearchFilter;
+import com.itasocialacademy.oitassist.competition.dto.request.ChangeCompetitionStatusRequest;
 import com.itasocialacademy.oitassist.competition.dto.request.CreateCompetitionRequest;
 import com.itasocialacademy.oitassist.competition.dto.response.CompetitionResponse;
 import com.itasocialacademy.oitassist.competition.dto.response.CompetitionTreeResponse;
@@ -94,21 +95,23 @@
 
     @Override
     @Transactional
-    public CompetitionResponse changeStatus(Long competitionId, CompetitionStatus status) {
+    public CompetitionResponse changeStatus(Long competitionId, ChangeCompetitionStatusRequest request) {
         Competition competition = competitionRepository.findById(competitionId)
             .orElseThrow(() -> new CompetitionNotFoundException(competitionId));
 
+        validator.validateEntityVersion(request.version(), competition.getVersion(), Competition.class, competitionId);
         CompetitionStatus currentStatus = competition.getCompetitionStatus();
 
-        validator.validateCompetitionStatusTransition(currentStatus, status);
+        validator.validateCompetitionStatusTransition(currentStatus, request.status());
 
-        if (status == CompetitionStatus.ENROLLMENT || status == CompetitionStatus.PUBLISHED) {
+        if (request.status() == CompetitionStatus.ENROLLMENT
+            || request.status() == CompetitionStatus.PUBLISHED) {
             validatePublishingRequirements(competitionId);
         } else if (status == CompetitionStatus.FINISHED) {
             validator.validateAllStagesCompletedForCompetition(competitionId);
         }
 
-        competition.setCompetitionStatus(status);
+        competition.setCompetitionStatus(request.status());
         return mapper.toResponse(competitionRepository.save(competition));
     }
 

src/main/java/com/itasocialacademy/oitassist/competition/service/StageServiceImpl.java

@@ -83,6 +83,8 @@ public StageResponse update(Long compId, Long stageId, UpdateStageRequest reques
         Stage stage = stageRepository.findById(stageId)
             .orElseThrow(() -> new StageNotFoundException(stageId));
 
+        validator.validateEntityVersion(request.version(), stage.getVersion(), Stage.class, stageId);
+
         validator.validateStageEligibility(compId, stage.getCompetitionId());
         validator.validateImmutabilityByCompetitionId(stage.getCompetitionId());
         validator.validateStageDates(stage.getCompetitionId(), request.dateStart(), request.dateFinish());
@@ -125,6 +127,8 @@ public StageResponse changeStatus(Long compId, Long stageId, ChangeStageStatusRe
         Stage stage = stageRepository.findById(stageId)
             .orElseThrow(() -> new StageNotFoundException(stageId));
 
+        validator.validateEntityVersion(request.version(), stage.getVersion(), Stage.class, stageId);
+
         validator.validateStageEligibility(compId, stage.getCompetitionId());
         validator.checkIfCompetitionPublishedByCompetitionId(compId);
         validator.validateStageStatusTransition(stage.getStatus(), request.status());

src/main/java/com/itasocialacademy/oitassist/competition/service/TourServiceImpl.java

@@ -77,6 +77,8 @@ public TourResponse update(Long pathStageId, Long tourId, UpdateTourRequest requ
         Tour tour = tourRepository.findById(tourId)
             .orElseThrow(() -> new TourNotFoundException(tourId));
 
+        validator.validateEntityVersion(request.version(), tour.getVersion(), Tour.class, tourId);
+
         validator.validateTourEligibility(pathStageId, tour.getStageId());
         validator.validateImmutabilityByStageId(tour.getStageId());
         validator.validateTourDates(tour.getStageId(), request.dateStart(), request.dateFinish());
@@ -114,6 +116,8 @@ public TourResponse changeStatus(Long stageId, Long tourId, ChangeTourStatusRequ
         Tour tour = tourRepository.findById(tourId)
             .orElseThrow(() -> new TourNotFoundException(tourId));
 
+        validator.validateEntityVersion(request.version(), tour.getVersion(), Tour.class, tourId);
+
         validator.validateTourEligibility(stageId, tour.getStageId());
         validator.checkIfCompetitionPublishedByStageId(stageId);
         validator.checkIfStageInProgress(stageId, request.status());

src/main/java/com/itasocialacademy/oitassist/competition/service/interfaces/CompetitionService.java

@@ -1,7 +1,7 @@
 package com.itasocialacademy.oitassist.competition.service.interfaces;
 
-import com.itasocialacademy.oitassist.competition.dao.enums.CompetitionStatus;
 import com.itasocialacademy.oitassist.competition.dto.filter.CompetitionSearchFilter;
+import com.itasocialacademy.oitassist.competition.dto.request.ChangeCompetitionStatusRequest;
 import com.itasocialacademy.oitassist.competition.dto.request.CreateCompetitionRequest;
 import com.itasocialacademy.oitassist.competition.dto.response.CompetitionResponse;
 import com.itasocialacademy.oitassist.competition.dto.response.CompetitionTreeResponse;
@@ -32,14 +32,14 @@ public interface CompetitionService {
     CompetitionResponse getVisibleById(Long competitionId);
 
     /**
-     * Transitions the competition to a new status. Publishing requires at least one
-     * Stage and one Tour.
+     * Transitions the competition to a new request. Publishing requires at least
+     * one Stage and one Tour.
      *
      * @param competitionId Competition ID
-     * @param status        a status of a Competition
+     * @param request       a request of a Competition
      * @return {@link CompetitionResponse}
      */
-    CompetitionResponse changeStatus(Long competitionId, CompetitionStatus status);
+    CompetitionResponse changeStatus(Long competitionId, ChangeCompetitionStatusRequest request);
 
     /**
      * Retrieves a paginated list of competitions visible to the current user,

src/main/java/com/itasocialacademy/oitassist/competition/validation/HierarchyValidator.java

@@ -12,10 +12,12 @@
 import com.itasocialacademy.oitassist.competition.exceptions.CompetitionHierarchyValidationException;
 import com.itasocialacademy.oitassist.competition.exceptions.CompetitionNotFoundException;
 import com.itasocialacademy.oitassist.competition.exceptions.StageNotFoundException;
+import com.itasocialacademy.oitassist.competition.exceptions.StaleEntityVersionException;
 import com.itasocialacademy.oitassist.competition.spi.ParticipationInquiryPort;
 import com.itasocialacademy.oitassist.security.api.interfaces.SecurityFacade;
 import java.time.ZonedDateTime;
 import java.util.List;
+import java.util.Objects;
 import java.util.Optional;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.AccessDeniedException;
@@ -352,4 +354,10 @@ public void validateTourEligibilityToResume(Tour tour) {
                     .formatted(tour.getTitle(), tour.getDateFinish()));
         }
     }
+
+    public void validateEntityVersion(Long expectedVersion, Long actualVersion, Class<?> entityClass, Long entityId) {
+        if (!Objects.equals(expectedVersion, actualVersion)) {
+            throw new StaleEntityVersionException(entityClass, entityId);
+        }
+    }
 }

src/main/java/com/itasocialacademy/oitassist/core/enums/ErrorCode.java

@@ -72,7 +72,10 @@ public enum ErrorCode {
     LOG_FILE_LISTING_FAILED(ErrorCategory.TECHNICAL),
     INVALID_LOG_FILE_SORT(ErrorCategory.VALIDATION),
 
-    DATA_ACCESS_ERROR(ErrorCategory.TECHNICAL);
+    DATA_ACCESS_ERROR(ErrorCategory.TECHNICAL),
+
+    ENTITY_VERSION_CONFLICT(ErrorCategory.CONFLICT),
+    COMMON_CONFLICT(ErrorCategory.CONFLICT);
 
     private final ErrorCategory category;
 }

src/main/java/com/itasocialacademy/oitassist/core/web/GlobalExceptionHandler.java

@@ -8,6 +8,7 @@
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.slf4j.MDC;
+import org.springframework.dao.OptimisticLockingFailureException;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.http.converter.HttpMessageNotReadableException;
@@ -226,6 +227,19 @@ public ResponseEntity<ErrorResponse> handleAccessDenied(
                 null));
     }
 
+    @ExceptionHandler(OptimisticLockingFailureException.class)
+    public ResponseEntity<ErrorResponse> handleOptimisticLockingFailure(
+        OptimisticLockingFailureException ex, HttpServletRequest request) {
+        log.warn("Optimistic locking conflict: traceId={}", MDC.get(TRACE_ID_MDC));
+        return ResponseEntity.status(HttpStatus.CONFLICT)
+            .body(buildResponse(
+                request,
+                ErrorCode.ENTITY_VERSION_CONFLICT,
+                "This resource was modified by someone else. Please refresh and try again.",
+                HttpStatus.CONFLICT.value(),
+                null));
+    }
+
     /**
      * Handles {@link MissingServletRequestPartException} by generating an
      * appropriate error response. This exception is thrown when a required part of

src/main/resources/db/changelog/db.changelog-master.xml

@@ -28,4 +28,5 @@
     <include file="/db/changelog/logs/2026-07-27-ch-alter-invitations-Haleliuk.xml"/>
     <include file="/db/changelog/logs/2026-08-04-ch-create-task-owners-table-Murashko.xml"/>
     <include file="/db/changelog/logs/2026-08-13-ch-add-news-updated-at-Rakuta.xml"/>
+    <include file="/db/changelog/logs/2026-08-11-ch-add-version-to-competitions-Pampukha.xml"/>
 </databaseChangeLog>

src/main/resources/db/changelog/logs/2026-08-11-ch-add-version-to-competitions-Pampukha.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
+                   https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">
+
+
+  <changeSet id="add-version-to-competitions" author="Anton Pampukha">
+    <addColumn tableName="competitions">
+      <column name="version" type="BIGINT" defaultValueNumeric="0">
+        <constraints nullable="false"/>
+      </column>
+    </addColumn>
+  </changeSet>
+
+  <changeSet id="add-version-to-stages" author="Anton Pampukha">
+    <addColumn tableName="stages">
+      <column name="version" type="BIGINT" defaultValueNumeric="0">
+        <constraints nullable="false"/>
+      </column>
+    </addColumn>
+  </changeSet>
+
+  <changeSet id="add-version-to-tours" author="Anton Pampukha">
+    <addColumn tableName="tours">
+      <column name="version" type="BIGINT" defaultValueNumeric="0">
+        <constraints nullable="false"/>
+      </column>
+    </addColumn>
+  </changeSet>
+</databaseChangeLog>