Merge branch 'dev' into feature/add-integration-test-reproducing-the-race-in-competition

Author: antonpampukha

src/main/java/com/itasocialacademy/oitassist/chat/controller/ParticipantForumController.java

@@ -21,127 +21,159 @@
 import org.springframework.web.bind.annotation.*;
 
 @RestController
-@RequestMapping("/api/v1/tasks/{taskId}/questions")
+@RequestMapping("/api/v1/task-assignments/{taskAssignmentId}/questions")
 @RequiredArgsConstructor
 @PreAuthorize("isAuthenticated()")
 @Tag(
     name = "Participant Forum V1",
-    description = "Participant operations for temporary TaskBody-scoped question forums")
+    description = "Participant operations for TaskAssignment-scoped question forums")
 public class ParticipantForumController {
     private final ParticipantForumService participantForumService;
 
     @Operation(
-        summary = "Get participant forum questions",
+        summary = "Get task assignment forum questions",
         description = """
-            Returns a paginated list of questions for the specified task.
+            Returns a paginated list of questions for the specified task assignment.
 
-            The response contains public questions and private questions created by
-            the authenticated participant. Questions are ordered by creation time
-            in descending order, with the question ID used as a deterministic
-            tie-breaker.
+            For an authenticated participant, the response contains public questions
+            and private questions created by that participant. Participant access
+            requires the task assignment to be visible and requires a matching
+            Participation for the assignment's competition and stage.
 
-            This is a temporary TaskBody-scoped API that will be migrated to
-            TaskAssignment-scoped access.
+            A global administrator may access an existing task assignment forum
+            without a participant record.
+
+            Questions are ordered by creation time in descending order, with the
+            question identifier used as a deterministic tie-breaker.
             """)
     @ApiResponses(value = {
         @ApiResponse(
             responseCode = "200",
-            description = "Forum questions retrieved successfully",
+            description = "Task assignment forum page retrieved successfully",
             content = @Content(
                 mediaType = "application/json",
-                schema = @Schema(implementation = PageResponse.class))),
+                schema = @Schema(
+                    implementation = PageResponse.class))),
         @ApiResponse(
             responseCode = "400",
-            description = "Task identifier or pagination parameters are invalid",
+            description = "Task assignment identifier or pagination parameters are invalid",
             content = @Content(
                 mediaType = "application/json",
-                schema = @Schema(implementation = ErrorResponse.class))),
+                schema = @Schema(
+                    implementation = ErrorResponse.class))),
         @ApiResponse(
             responseCode = "401",
             description = "Authentication is required",
             content = @Content(
                 mediaType = "application/json",
-                schema = @Schema(implementation = ErrorResponse.class))),
+                schema = @Schema(
+                    implementation = ErrorResponse.class))),
+        @ApiResponse(
+            responseCode = "403",
+            description = "The task assignment is hidden or matching participation is missing",
+            content = @Content(
+                mediaType = "application/json",
+                schema = @Schema(
+                    implementation = ErrorResponse.class))),
         @ApiResponse(
             responseCode = "404",
-            description = "Task was not found",
+            description = "The task assignment, related tour, or related stage was not found",
             content = @Content(
                 mediaType = "application/json",
-                schema = @Schema(implementation = ErrorResponse.class)))
+                schema = @Schema(
+                    implementation = ErrorResponse.class)))
     })
     @GetMapping
     public ResponseEntity<PageResponse<QuestionThreadSummaryResponseDTO>> getParticipantForum(
         @Parameter(
-            description = "Positive identifier of the task whose forum is requested",
+            description = "Positive identifier of the task assignment whose forum is requested",
             example = "42",
-            required = true) @PathVariable Long taskId,
-
+            required = true) @PathVariable Long taskAssignmentId,
         @Parameter(
             description = "Zero-based page number",
             example = "0") @RequestParam(defaultValue = "0") int page,
-
         @Parameter(
             description = "Number of questions per page. Must be between 1 and 100",
             example = "20") @RequestParam(defaultValue = "20") int size) {
         return ResponseEntity.ok(
-            PageResponse.from(
-                participantForumService.getForumQuestions(
-                    taskId,
-                    page,
-                    size)));
+            PageResponse.from(participantForumService.getForumQuestions(taskAssignmentId, page, size)));
     }
 
     @Operation(
-        summary = "Create a participant question",
+        summary = "Create a question in a task assignment forum",
         description = """
-            Creates a private question in the forum of the specified task.
+            Creates a private question in the forum of the specified task assignment.
+
+            For a participant, the task assignment must be visible and a matching
+            Participation must exist for the assignment's competition and stage.
+            A global administrator may access an existing task assignment forum
+            without a participant record.
+
+            The related tour must have the IN_PROGRESS execution status.
 
             The authenticated user becomes the question author. The backend assigns
-            the initial status NEW, state OPEN, visibility PRIVATE, an empty reviewer,
-            and version zero.
+            status NEW, state OPEN, visibility PRIVATE, no reviewer, and version zero.
 
-            The request may provide only the question title and content. This is a
-            temporary TaskBody-scoped API that will be migrated to
-            TaskAssignment-scoped access.
+            The request may provide only the question title and content. The task
+            assignment identifier and all workflow fields are controlled by the
+            backend.
             """)
-    @ApiResponses(value = {
-        @ApiResponse(
-            responseCode = "201",
-            description = "Question created successfully",
-            content = @Content(
-                mediaType = "application/json",
-                schema = @Schema(implementation = QuestionThreadResponseDTO.class))),
-        @ApiResponse(
-            responseCode = "400",
-            description = "Task identifier or request body is invalid",
-            content = @Content(
-                mediaType = "application/json",
-                schema = @Schema(implementation = ErrorResponse.class))),
-        @ApiResponse(
-            responseCode = "401",
-            description = "Authentication is required",
-            content = @Content(
-                mediaType = "application/json",
-                schema = @Schema(implementation = ErrorResponse.class))),
-        @ApiResponse(
-            responseCode = "404",
-            description = "Task was not found",
-            content = @Content(
-                mediaType = "application/json",
-                schema = @Schema(implementation = ErrorResponse.class)))
-    })
+    @ApiResponses(
+        value = {
+            @ApiResponse(
+                responseCode = "201",
+                description = "Question created successfully",
+                content = @Content(
+                    mediaType = "application/json",
+                    schema = @Schema(
+                        implementation = QuestionThreadResponseDTO.class))),
+            @ApiResponse(
+                responseCode = "400",
+                description = "Task assignment identifier or request body is invalid",
+                content = @Content(
+                    mediaType = "application/json",
+                    schema = @Schema(
+                        implementation = ErrorResponse.class))),
+            @ApiResponse(
+                responseCode = "401",
+                description = "Authentication is required",
+                content = @Content(
+                    mediaType = "application/json",
+                    schema = @Schema(
+                        implementation = ErrorResponse.class))),
+            @ApiResponse(
+                responseCode = "403",
+                description = "The task assignment is hidden or matching participation is missing",
+                content = @Content(
+                    mediaType = "application/json",
+                    schema = @Schema(
+                        implementation = ErrorResponse.class))),
+            @ApiResponse(
+                responseCode = "404",
+                description = "The task assignment, related tour, or related stage was not found",
+                content = @Content(
+                    mediaType = "application/json",
+                    schema = @Schema(
+                        implementation = ErrorResponse.class))),
+            @ApiResponse(
+                responseCode = "409",
+                description = "Question creation is not allowed because the related tour is not in progress",
+                content = @Content(
+                    mediaType = "application/json",
+                    schema = @Schema(
+                        implementation = ErrorResponse.class)))
+        })
     @PostMapping
     public ResponseEntity<QuestionThreadResponseDTO> createQuestion(
         @Parameter(
-            description = "Positive identifier of the task in which the question is created",
+            description = "Positive identifier of the task assignment in which the question is created",
             example = "42",
-            required = true) @PathVariable Long taskId,
+            required = true) @PathVariable Long taskAssignmentId,
         @Valid @RequestBody CreateQuestionRequestDTO request) {
-        QuestionThreadResponseDTO response =
-            participantForumService.createQuestion(taskId, request);
+        QuestionThreadResponseDTO response = participantForumService.createQuestion(taskAssignmentId, request);
 
         return ResponseEntity
             .status(HttpStatus.CREATED)
             .body(response);
     }
-}
+}

src/main/java/com/itasocialacademy/oitassist/chat/dao/dto/response/QuestionThreadResponseDTO.java

@@ -11,7 +11,7 @@
 @Schema(description = "Foundational question thread response")
 public record QuestionThreadResponseDTO(
     Long id,
-    Long taskId,
+    Long taskAssignmentId,
     Long authorId,
     Long assignedReviewerId,
     String title,

src/main/java/com/itasocialacademy/oitassist/chat/dao/dto/response/QuestionThreadSummaryResponseDTO.java

@@ -11,7 +11,7 @@
 @Schema(description = "Question thread summary displayed in the participant forum")
 public record QuestionThreadSummaryResponseDTO(
     Long id,
-    Long taskId,
+    Long taskAssignmentId,
     Long authorId,
     String title,
     QuestionStatus status,

src/main/java/com/itasocialacademy/oitassist/chat/dao/model/QuestionThread.java

@@ -38,13 +38,8 @@ public class QuestionThread {
     @GeneratedValue(strategy = GenerationType.IDENTITY)
     private Long id;
 
-    /**
-     * TODO change after TaskAssignment is implemented. Temporary TaskBody
-     * reference. This field should be replaced with taskAssignmentId after
-     * TaskAssignment is implemented.
-     */
-    @Column(name = "task_id", nullable = false)
-    private Long taskId;
+    @Column(name = "task_assignment_id", nullable = false)
+    private Long taskAssignmentId;
 
     @CreatedBy
     @Column(name = "author_id", nullable = false, updatable = false)

src/main/java/com/itasocialacademy/oitassist/chat/dao/repository/QuestionThreadRepository.java

@@ -13,7 +13,7 @@ public interface QuestionThreadRepository extends JpaRepository<QuestionThread,
     @Query("""
         SELECT question
         FROM QuestionThread question
-        WHERE question.taskId = :taskId
+        WHERE question.taskAssignmentId = :taskAssignmentId
           AND (
               question.visibility = PUBLIC
               OR (
@@ -23,7 +23,7 @@ public interface QuestionThreadRepository extends JpaRepository<QuestionThread,
           )
         """)
     Page<QuestionThread> findParticipantVisibleQuestions(
-        @Param("taskId") Long taskId,
+        @Param("taskAssignmentId") Long taskAssignmentId,
         @Param("participantId") Long participantId,
         Pageable pageable);
 }

src/main/java/com/itasocialacademy/oitassist/chat/exceptions/QuestionCreationNotAllowedException.java

@@ -0,0 +1,14 @@
+package com.itasocialacademy.oitassist.chat.exceptions;
+
+import com.itasocialacademy.oitassist.competition.dao.enums.ExecutionStatus;
+import com.itasocialacademy.oitassist.core.enums.ErrorCode;
+import com.itasocialacademy.oitassist.core.exceptions.BusinessException;
+
+public class QuestionCreationNotAllowedException extends BusinessException {
+    public QuestionCreationNotAllowedException(Long taskAssignmentId, ExecutionStatus executionStatus) {
+        super(
+            "Question creation is not allowed for task assignment with id %s while the tour status is %s"
+                .formatted(taskAssignmentId, executionStatus),
+            ErrorCode.QUESTION_INVALID_STATE);
+    }
+}

src/main/java/com/itasocialacademy/oitassist/chat/exceptions/QuestionForumAccessRestrictedException.java

@@ -0,0 +1,13 @@
+package com.itasocialacademy.oitassist.chat.exceptions;
+
+import com.itasocialacademy.oitassist.core.enums.ErrorCode;
+import com.itasocialacademy.oitassist.core.exceptions.AuthorizationException;
+
+public class QuestionForumAccessRestrictedException extends AuthorizationException {
+    public QuestionForumAccessRestrictedException(Long taskAssignmentId) {
+        super(
+            "Access to the question forum for task assignment with id %s is restricted"
+                .formatted(taskAssignmentId),
+            ErrorCode.QUESTION_ACCESS_RESTRICTED);
+    }
+}

src/main/java/com/itasocialacademy/oitassist/chat/package-info.java

@@ -1,7 +1,11 @@
 @ApplicationModule(
     displayName = "Chat",
     allowedDependencies = {"core", "core :: AuthenticationException", "security :: SecurityFacade",
-        "task :: api", "task :: dto", "task :: exceptions"})
+        "taskassignment :: api", "taskassignment :: dto",
+        "taskassignment :: enums", "taskassignment :: exceptions",
+        "competition :: api", "competition :: dto",
+        "competition :: enums", "competition :: exceptions",
+        "participation :: api"})
 package com.itasocialacademy.oitassist.chat;
 
 import org.springframework.modulith.ApplicationModule;