Merge pull request #1118 from IT-Academy-BCN/feature/190-2/point-history-retrival-logic

[BE] PR 2/3: Point History Retrieval Logic (#216)

Author: ivilarop

CHANGELOG.md

@@ -3,17 +3,25 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [UNRELEASED] 2026-02-19
+### Added
+- PointsHistoryResponseDto: New DTO to encapsulate the response structure, including total points and the collection of user activities.
+- PointHistoryEntryDto: New DTO for individual score entries, including points and formatted date strings.
+- UserScoreService: Core interface definition for gamification point-related business operations.
+- UserScoreServiceImpl: Implementation of the points history logic, featuring reactive stream processing and score aggregation.
+- UserScoreServiceImplTest: Comprehensive unit test suite for PointsServiceImpl covering all business requirements.
+
 ### [itachallenge-user-3.2.3-RELEASE] - 2026-02-18
 
 ### Removed
 - Removed deprecated legacy Bookmarks routes previously served by BookmarkLegacyController. (GitHub Task [#186], PR [#1106])
-- 
 ## [UNRELEASED]
 
 ### Added
 - New MongoDB collection `user_score_history` with compound indexing for efficient retrieval for gamification tracking.
 - Reactive Repository for user score transactions.
 
+## [Unreleased]
 ### [itachallenge-user-3.2.2-RELEASE] - 2026-02-23
 
 ### Removed
@@ -67,12 +75,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Submission domain bootstrap (documents, repository, service layer and DTOs).
 - New `SubmissionController` exposing read endpoints for user submissions.
-
+ 
 ### [itachallenge-challenge-3.0.4-RELEASE] - 2025-12-17
 
 ### Fixed
 - Updated the favorites integration path to point to the new `FavoriteController` of the `user` micro.
-  (No changes to the public `challenge` API. Bookmarks remains the same.)
+(No changes to the public `challenge` API. Bookmarks remains the same.)
 
 ### [itachallenge-user-3.1.3-RELEASE] - 2025-12-12
 
@@ -110,11 +118,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Breaking Change
 - API Contract: Replaced the `status` field with action in UserSolutionRequestDto.
-  Supported actions: SAVE, GIVE_UP, SUBMIT. (Taiga [#871], PR [#1043])
+Supported actions: SAVE, GIVE_UP, SUBMIT. (Taiga [#871], PR [#1043])
 - New SolutionAction enum : Action-based submission workflow: Implemented business logic to map user actions to internal solution statuses:
-  - SAVE → IN_PROGRESS
-  - GIVE_UP → SUBMITTED_UNCOMPLETED
-  - SUBMIT → SUBMITTED_COMPLETED
+    - SAVE → IN_PROGRESS
+    - GIVE_UP → SUBMITTED_UNCOMPLETED
+    - SUBMIT → SUBMITTED_COMPLETED
 - Updated OpenAPI documentation.
 
 ## [Unreleased]
@@ -185,10 +193,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Foundation for managing user favorites in a dedicated collection.
   - Favorite domain & persistence
-    - FavoriteDocument & FavoriteDocumentTest
+    - FavoriteDocument & FavoriteDocumentTest 
     - FavoriteRepository (ReactiveMongoRepository<FavoriteDocument, UUID>) ; Favorites collection starts empty.
     - FavoriteResponseDto & FavoriteResponseDtoTest
-
+ 
 
 ### Changed
 - UserServiceImpl
@@ -226,20 +234,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Now returns 503 Service Unavailable or 504 Gateway Timeout instead of a generic 500.
   - Introduced `GithubUnavailableException` to encapsulate timeout and unavailability causes.
   - Updated `UserGlobalExceptionHandler` to map these cases accordingly.
-  -
+  - 
 ### [itachallenge-user-3.0.0-RELEASE] - 2025-10-09
 
 ### Changed
-- Before: SolutionStatus enum only had two options `ENDED` and `IN_PROGRESS`, solutions with status `ENDED` could be modified,
+- Before: SolutionStatus enum only had two options `ENDED` and `IN_PROGRESS`, solutions with status `ENDED` could be modified, 
   leading to ambiguity in submission state.
 - After: SolutionStatus enum options can be marked as `IN_PROGRESS`, `SUBMITTED_COMPLETE` or `SUBMITTED_INCOMPLETE`.
   Solutions marked as `SUBMITTED_COMPLETE` or `SUBMITTED_INCOMPLETE` now throw `UnmodifiableSolutionException`
   when updated. Only `IN_PROGRESS` solutions remain editable.
 - This changes prevents accidental overwrites of finalized submissions.
 - this changes will break the communication between back and frontend, it is required to adjust the type of answer that can be submitted
-  by users ENDED is replaced with SUBMITTED_COMPLETE and SUBMITTED_INCOMPLETE has to be added to better reflect the status
+  by users ENDED is replaced with SUBMITTED_COMPLETE and SUBMITTED_INCOMPLETE has to be added to better reflect the status 
   in which challenges can be set (Taiga user story [#703])
-
+  
 ### [itachallenge-user-2.1.0-RELEASE] - 2025-10-03
 
 ### Added
@@ -256,8 +264,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Added github username validation to user microservice upon creation of a new user (Taiga [#650], PR [#960])
-  - Before: POST /users/create accepted any githubUsername value and returned success (201/ok) even if that wasn't a GitHub username.
-  - After: POST /users/create now calls the GitHub API and rejects the request when the GitHub username does not exist.
+  - Before: POST /users/create accepted any githubUsername value and returned success (201/ok) even if that wasn't a GitHub username. 
+  - After: POST /users/create now calls the GitHub API and rejects the request when the GitHub username does not exist. 
   - Clients that previously relied on creating users with invalid GitHub usernames will now get errors for some requests that used to succeed.
 
 ### [itachallenge-githubcore-1.0.0-RELEASE] - 2025-09-11
@@ -369,15 +377,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Add validation to verify that the provided user ID exists for the getAllSolutionsByUser endpoint. (Taiga [#437], PR [#889])
-- FavoriteController and extracted endpoints from ChallengeController. (Taiga [#418], PR [#886])
-- POST endpoint in Auth microservice to allow user role change at runtime (Taiga [#404], PR [#882])
-- Hardcoded GET endpoint to return all of a user’s challenge solutions (Taiga [#435], PR [#884])
-- JWT authentication to logout endpoint in User microservice (Taiga [#399], PR [#864])
-- Error handling for malformed tag UUIDs and duplicate UUID detection in TagServiceImpl.getValidatedTags (Taiga [#355], PR [#872])
-- Tag validation in the addChallenge endpoint (Taiga [#354], PR [#866])
+- FavoriteController and extracted endpoints from ChallengeController. (Taiga [#418], PR [#886]) 
+- POST endpoint in Auth microservice to allow user role change at runtime (Taiga [#404], PR [#882])  
+- Hardcoded GET endpoint to return all of a user’s challenge solutions (Taiga [#435], PR [#884])  
+- JWT authentication to logout endpoint in User microservice (Taiga [#399], PR [#864])  
+- Error handling for malformed tag UUIDs and duplicate UUID detection in TagServiceImpl.getValidatedTags (Taiga [#355], PR [#872]) 
+- Tag validation in the addChallenge endpoint (Taiga [#354], PR [#866])  
 - GET endpoint for retrieving resources from a challenge (Taiga [#281], PR [#852])
-- GET endpoint to retrieve all user's bookmarked challenges (Taiga [#255], PR [#849])
-- DELETE endpoint in Challenge microservice to unbookmark a challenge (Taiga [#205], PR [#843])
+- GET endpoint to retrieve all user's bookmarked challenges (Taiga [#255], PR [#849]) 
+- DELETE endpoint in Challenge microservice to unbookmark a challenge (Taiga [#205], PR [#843]) 
 - POST endpoint in Challenge microservice to bookmark a challenge (Taiga [#183], PR [#829])
 - POST endpoint in User microservice to bookmark a challenge (Taiga [#183], PR [#827])
 - DELETE endpoint for user's bookmarks in User microservice (Taiga [#205], PR [#831])
@@ -389,7 +397,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Replaced Hardcoded GET endpoint to return all of a user’s challenge solutions with actual solutions (Taiga [#406], PR [#887])
 - POST endpoint for adding new challenges in Challenge microservice (PR #763)
 - Improved filtering at `/GET Challenges`: added DTO for filters (language, level, tags), refactored `filterByLanguage()`, `filterByLevel()`, and `filterByTags()` methods, and added `GET /allTags` endpoint (PR #180 & PR #185)
-- Modify method to increase times solved counter (Taiga [#415], PR [#885])
+- Modify method to increase times solved counter (Taiga [#415], PR [#885]) 
 
 ### Removed
 - Removed `score` attribute from `UserSolution` DTOs and cleaned up all score/solution-related code in User microservice (PR #825, PR #725)
@@ -436,4 +444,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * First version
 
 ### [docker-compose-1.0] - 2023-11-30
-* First version
+* First version

itachallenge-challenge/src/main/java/com/itachallenge/challenge/dto/gamification/PointHistoryEntryDto.java

@@ -0,0 +1,15 @@
+package com.itachallenge.challenge.dto.gamification;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.*;
+
+@Getter
+@Setter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class PointHistoryEntryDto {
+    @JsonProperty("date")
+    private String createdAt;
+    private int points;
+}

itachallenge-challenge/src/main/java/com/itachallenge/challenge/dto/gamification/PointsHistoryResponseDto.java

@@ -0,0 +1,16 @@
+package com.itachallenge.challenge.dto.gamification;
+
+import lombok.*;
+
+import java.util.List;
+
+@Getter
+@Setter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class PointsHistoryResponseDto {
+    private String username;
+    private int totalPoints;
+    private List<PointHistoryEntryDto> history;
+}

itachallenge-challenge/src/main/java/com/itachallenge/gamification/service/UserScoreService.java

@@ -0,0 +1,12 @@
+package com.itachallenge.gamification.service;
+
+import com.itachallenge.challenge.dto.gamification.PointsHistoryResponseDto;
+import reactor.core.publisher.Mono;
+
+import java.util.UUID;
+
+public interface UserScoreService {
+
+    Mono<PointsHistoryResponseDto> getUserPointsHistory(UUID userId);
+}
+

itachallenge-challenge/src/main/java/com/itachallenge/gamification/service/UserScoreServiceImpl.java

@@ -0,0 +1,51 @@
+package com.itachallenge.gamification.service;
+
+import com.itachallenge.challenge.dto.gamification.PointHistoryEntryDto;
+import com.itachallenge.challenge.dto.gamification.PointsHistoryResponseDto;
+import com.itachallenge.gamification.document.UserScoreDocument;
+import com.itachallenge.gamification.repository.UserScoreRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import reactor.core.publisher.Mono;
+
+import java.util.Comparator;
+import java.util.List;
+import java.util.Objects;
+import java.util.UUID;
+
+@Service
+@RequiredArgsConstructor
+public class UserScoreServiceImpl implements UserScoreService {
+
+    private final UserScoreRepository userScoreRepository;
+
+    @Override
+    public Mono<PointsHistoryResponseDto> getUserPointsHistory(UUID userId) {
+        return userScoreRepository.findByUserIdOrderByCreatedAtDesc(userId)
+                .collectList()
+                .map(this::buildHistoryResponse);
+    }
+
+    private PointsHistoryResponseDto buildHistoryResponse(List<UserScoreDocument> docs) {
+        int totalPoints = docs.stream()
+                .map(UserScoreDocument::getPointsEarned)
+                .filter(Objects::nonNull)
+                .mapToInt(Integer::intValue)
+                .sum();
+
+        List<PointHistoryEntryDto> history = docs.stream()
+                .sorted(Comparator.comparing(UserScoreDocument::getCreatedAt,
+                        Comparator.nullsLast(Comparator.naturalOrder())))
+                .map(doc -> PointHistoryEntryDto.builder()
+                        .createdAt(doc.getCreatedAt() != null ? doc.getCreatedAt().toString() : "")
+                        .points(doc.getPointsEarned() != null ? doc.getPointsEarned() : 0)
+                        .build())
+                .toList();
+
+        return PointsHistoryResponseDto.builder()
+                .username(docs.isEmpty() ? "" : docs.getFirst().getUsername())
+                .totalPoints(totalPoints)
+                .history(history)
+                .build();
+    }
+}

itachallenge-challenge/src/test/java/com/itachallenge/challenge/dto/gamification/PointsHistoryResponseDtoTest.java

@@ -0,0 +1,45 @@
+package com.itachallenge.challenge.dto.gamification;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.json.JsonTest;
+import org.springframework.boot.test.json.JacksonTester;
+import org.springframework.boot.test.json.JsonContent;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.fail;
+
+@JsonTest
+class PointsHistoryResponseDtoTest {
+
+    @Autowired
+    private JacksonTester<PointsHistoryResponseDto> json;
+
+    @Test
+    void testSerializationContract() {
+        try {
+            PointHistoryEntryDto entry = PointHistoryEntryDto.builder()
+                    .createdAt("2011-01-11T11:11:11")
+                    .points(10)
+                    .build();
+
+            PointsHistoryResponseDto dto = PointsHistoryResponseDto.builder()
+                    .username("testUser")
+                    .totalPoints(10)
+                    .history(List.of(entry))
+                    .build();
+
+            JsonContent<PointsHistoryResponseDto> result = json.write(dto);
+
+            assertThat(result).hasJsonPathStringValue("@.username", "testUser");
+            assertThat(result).hasJsonPathNumberValue("@.totalPoints", 10);
+            assertThat(result).hasJsonPathStringValue("@.history[0].date", "2011-01-11T11:11:11");
+            assertThat(result).hasJsonPathNumberValue("@.history[0].points", 10);
+            assertThat(result).doesNotHaveJsonPath("@.history[0].createdAt");
+        } catch (Exception e) {
+            fail("Serialization failed: " + e.getMessage());
+        }
+    }
+}

itachallenge-challenge/src/test/java/com/itachallenge/gamification/repository/UserScoreRepositoryTest.java

@@ -22,7 +22,6 @@ class UserScoreRepositoryTest {
     @Test
     void givenExistingScores_whenFindByUsername_thenReturnsSortedByDescendingDates() {
         UUID userId = UUID.randomUUID();
-
         UserScoreDocument score1 = UserScoreDocument.builder()
                 .id(UUID.randomUUID())
                 .userId(userId)