Merge pull request #115 from pierrick-fonquerne/58-galerie-des-personnages

feat: galerie publique des personnages (#58)

Author: pierrick-fonquerne

src/backend/src/FantasyRealm.Api/Controllers/CharactersController.cs

@@ -1,4 +1,5 @@
 using System.IdentityModel.Tokens.Jwt;
+using FantasyRealm.Application.Common;
 using FantasyRealm.Application.DTOs;
 using FantasyRealm.Application.Interfaces;
 using Microsoft.AspNetCore.Authorization;
@@ -61,6 +62,36 @@ public async Task<IActionResult> GetMine(CancellationToken cancellationToken)
             return Ok(result.Value);
         }
 
+        /// <summary>
+        /// Returns a paginated list of approved and shared characters for the public gallery.
+        /// </summary>
+        /// <param name="gender">Optional gender filter (Male, Female).</param>
+        /// <param name="author">Optional author pseudo search (case-insensitive).</param>
+        /// <param name="sort">Sort order: recent (default), oldest, nameAsc.</param>
+        /// <param name="page">Page number (1-based, default 1).</param>
+        /// <param name="pageSize">Items per page (default 12, max 50).</param>
+        /// <param name="cancellationToken">Cancellation token.</param>
+        /// <returns>A paginated list of gallery characters.</returns>
+        /// <response code="200">Gallery characters retrieved successfully.</response>
+        [HttpGet]
+        [AllowAnonymous]
+        [ProducesResponseType(typeof(PagedResponse<GalleryCharacterResponse>), StatusCodes.Status200OK)]
+        public async Task<IActionResult> GetGallery(
+            [FromQuery] string? gender,
+            [FromQuery] string? author,
+            [FromQuery] string? sort,
+            [FromQuery] int page = 1,
+            [FromQuery] int pageSize = 12,
+            CancellationToken cancellationToken = default)
+        {
+            var result = await characterService.GetGalleryAsync(gender, author, sort, page, pageSize, cancellationToken);
+
+            if (result.IsFailure)
+                return StatusCode(result.ErrorCode ?? 400, new { message = result.Error });
+
+            return Ok(result.Value);
+        }
+
         /// <summary>
         /// Returns a character by its identifier.
         /// Authenticated owners see all their characters. Anonymous users see only approved shared characters.

src/backend/src/FantasyRealm.Application/Common/PagedResponse.cs

@@ -0,0 +1,13 @@
+namespace FantasyRealm.Application.Common
+{
+    /// <summary>
+    /// Represents a paginated response containing a subset of items and pagination metadata.
+    /// </summary>
+    /// <typeparam name="T">The type of items in the response.</typeparam>
+    public sealed record PagedResponse<T>(
+        IReadOnlyList<T> Items,
+        int Page,
+        int PageSize,
+        int TotalCount,
+        int TotalPages);
+}

src/backend/src/FantasyRealm.Application/DTOs/GalleryCharacterResponse.cs

@@ -0,0 +1,21 @@
+namespace FantasyRealm.Application.DTOs
+{
+    /// <summary>
+    /// Character data for the public gallery, including author information and appearance preview.
+    /// </summary>
+    public sealed record GalleryCharacterResponse(
+        int Id,
+        string Name,
+        string ClassName,
+        string Gender,
+        string AuthorPseudo,
+        DateTime CreatedAt,
+        string SkinColor,
+        string HairColor,
+        string EyeColor,
+        string FaceShape,
+        string HairStyle,
+        string EyeShape,
+        string NoseShape,
+        string MouthShape);
+}

src/backend/src/FantasyRealm.Application/Interfaces/ICharacterRepository.cs

@@ -1,3 +1,4 @@
+using FantasyRealm.Application.DTOs;
 using FantasyRealm.Domain.Entities;
 
 namespace FantasyRealm.Application.Interfaces
@@ -36,5 +37,18 @@ public interface ICharacterRepository
         /// Checks whether a character with the given name already exists for a specific user.
         /// </summary>
         Task<bool> ExistsByNameAndUserAsync(string name, int userId, int? excludeCharacterId, CancellationToken cancellationToken);
+
+        /// <summary>
+        /// Returns a paginated list of approved and shared characters for the public gallery.
+        /// Uses server-side projection to avoid loading sensitive user data into memory.
+        /// Supports optional filtering by gender and author pseudo, with configurable sorting.
+        /// </summary>
+        Task<(IReadOnlyList<GalleryCharacterResponse> Items, int TotalCount)> GetGalleryAsync(
+            string? gender,
+            string? authorPseudo,
+            string sortBy,
+            int page,
+            int pageSize,
+            CancellationToken cancellationToken);
     }
 }

src/backend/src/FantasyRealm.Application/Interfaces/ICharacterService.cs

@@ -67,5 +67,22 @@ public interface ICharacterService
         /// <param name="cancellationToken">Cancellation token.</param>
         /// <returns>The updated character with toggled IsShared value.</returns>
         Task<Result<CharacterResponse>> ToggleShareAsync(int characterId, int userId, CancellationToken cancellationToken);
+
+        /// <summary>
+        /// Returns a paginated list of approved and shared characters for the public gallery.
+        /// </summary>
+        /// <param name="gender">Optional gender filter (Male, Female).</param>
+        /// <param name="authorPseudo">Optional author pseudo search (case-insensitive).</param>
+        /// <param name="sortBy">Sort order: recent (default), oldest, nameAsc.</param>
+        /// <param name="page">Page number (1-based).</param>
+        /// <param name="pageSize">Number of items per page.</param>
+        /// <param name="cancellationToken">Cancellation token.</param>
+        Task<Result<PagedResponse<GalleryCharacterResponse>>> GetGalleryAsync(
+            string? gender,
+            string? authorPseudo,
+            string? sortBy,
+            int page,
+            int pageSize,
+            CancellationToken cancellationToken);
     }
 }

src/backend/src/FantasyRealm.Application/Services/CharacterService.cs

@@ -232,6 +232,37 @@ public async Task<Result<CharacterResponse>> ToggleShareAsync(int characterId, i
             return Result<CharacterResponse>.Success(MapToResponse(character, character.Class.Name, true));
         }
 
+        /// <inheritdoc />
+        public async Task<Result<PagedResponse<GalleryCharacterResponse>>> GetGalleryAsync(
+            string? gender,
+            string? authorPseudo,
+            string? sortBy,
+            int page,
+            int pageSize,
+            CancellationToken cancellationToken)
+        {
+            if (page < 1)
+                return Result<PagedResponse<GalleryCharacterResponse>>.Failure("Le numéro de page doit être supérieur à 0.");
+
+            if (page > 1000)
+                return Result<PagedResponse<GalleryCharacterResponse>>.Failure("Le numéro de page ne peut pas dépasser 1000.");
+
+            pageSize = Math.Clamp(pageSize, 1, 50);
+
+            var allowedSortValues = new[] { "recent", "oldest", "nameAsc" };
+            var sort = allowedSortValues.Contains(sortBy) ? sortBy! : "recent";
+
+            var sanitizedAuthor = SanitizeLikePattern(authorPseudo);
+
+            var (items, totalCount) = await characterRepository.GetGalleryAsync(
+                gender, sanitizedAuthor, sort, page, pageSize, cancellationToken);
+
+            var totalPages = (int)Math.Ceiling((double)totalCount / pageSize);
+
+            return Result<PagedResponse<GalleryCharacterResponse>>.Success(
+                new PagedResponse<GalleryCharacterResponse>(items, page, pageSize, totalCount, totalPages));
+        }
+
         private static CharacterResponse MapToResponse(Character character, string className, bool isOwner)
         {
             return new CharacterResponse(
@@ -273,5 +304,20 @@ private static CharacterSummaryResponse MapToSummaryResponse(Character character
                 character.NoseShape,
                 character.MouthShape);
         }
+
+        /// <summary>
+        /// Escapes LIKE-pattern metacharacters (<c>%</c>, <c>_</c>, <c>\</c>) in a search term
+        /// to prevent wildcard injection in PostgreSQL ILike queries.
+        /// </summary>
+        private static string? SanitizeLikePattern(string? value)
+        {
+            if (string.IsNullOrWhiteSpace(value))
+                return value;
+
+            return value
+                .Replace(@"\", @"\\")
+                .Replace("%", @"\%")
+                .Replace("_", @"\_");
+        }
     }
 }

src/backend/src/FantasyRealm.Infrastructure/Repositories/CharacterRepository.cs

@@ -1,5 +1,7 @@
+using FantasyRealm.Application.DTOs;
 using FantasyRealm.Application.Interfaces;
 using FantasyRealm.Domain.Entities;
+using FantasyRealm.Domain.Enums;
 using FantasyRealm.Infrastructure.Persistence;
 using Microsoft.EntityFrameworkCore;
 
@@ -62,5 +64,55 @@ public async Task<bool> ExistsByNameAndUserAsync(string name, int userId, int? e
                             && (!excludeCharacterId.HasValue || c.Id != excludeCharacterId.Value),
                     cancellationToken);
         }
+
+        /// <inheritdoc />
+        public async Task<(IReadOnlyList<GalleryCharacterResponse> Items, int TotalCount)> GetGalleryAsync(
+            string? gender,
+            string? authorPseudo,
+            string sortBy,
+            int page,
+            int pageSize,
+            CancellationToken cancellationToken)
+        {
+            var query = context.Characters
+                .Where(c => c.Status == CharacterStatus.Approved && c.IsShared);
+
+            if (!string.IsNullOrWhiteSpace(gender) && Enum.TryParse<Gender>(gender, true, out var parsedGender))
+                query = query.Where(c => c.Gender == parsedGender);
+
+            if (!string.IsNullOrWhiteSpace(authorPseudo))
+                query = query.Where(c => EF.Functions.ILike(c.User.Pseudo, $"%{authorPseudo}%"));
+
+            query = sortBy switch
+            {
+                "oldest" => query.OrderBy(c => c.CreatedAt),
+                "nameAsc" => query.OrderBy(c => c.Name),
+                _ => query.OrderByDescending(c => c.CreatedAt)
+            };
+
+            var totalCount = await query.CountAsync(cancellationToken);
+
+            var items = await query
+                .Skip((page - 1) * pageSize)
+                .Take(pageSize)
+                .Select(c => new GalleryCharacterResponse(
+                    c.Id,
+                    c.Name,
+                    c.Class.Name,
+                    c.Gender.ToString(),
+                    c.User.Pseudo,
+                    c.CreatedAt,
+                    c.SkinColor,
+                    c.HairColor,
+                    c.EyeColor,
+                    c.FaceShape,
+                    c.HairStyle,
+                    c.EyeShape,
+                    c.NoseShape,
+                    c.MouthShape))
+                .ToListAsync(cancellationToken);
+
+            return (items, totalCount);
+        }
     }
 }

src/backend/tests/FantasyRealm.Tests.Integration/Controllers/CharactersControllerIntegrationTests.cs

@@ -380,6 +380,66 @@ public async Task GetMine_ReturnsIsSharedProperty()
             characters![0].IsShared.Should().BeFalse();
         }
 
+        // ── Gallery ──────────────────────────────────────────────────────
+
+        [Fact]
+        public async Task Gallery_ReturnsEmptyList_WhenNoSharedCharacters()
+        {
+            var response = await _client.GetAsync("/api/characters");
+
+            response.StatusCode.Should().Be(HttpStatusCode.OK);
+            var gallery = await response.Content.ReadFromJsonAsync<GalleryResult>();
+            gallery!.Items.Should().BeEmpty();
+            gallery.TotalCount.Should().Be(0);
+        }
+
+        [Fact]
+        public async Task Gallery_DoesNotReturnDraftCharacters()
+        {
+            var token = await RegisterAndGetTokenAsync();
+            await PostAuthenticatedAsync("/api/characters", ValidCharacterPayload("DraftHero"), token);
+
+            var response = await _client.GetAsync("/api/characters");
+
+            response.StatusCode.Should().Be(HttpStatusCode.OK);
+            var gallery = await response.Content.ReadFromJsonAsync<GalleryResult>();
+            gallery!.Items.Should().BeEmpty();
+        }
+
+        [Fact]
+        public async Task Gallery_ReturnsPaginationMetadata()
+        {
+            var response = await _client.GetAsync("/api/characters?page=1&pageSize=12");
+
+            response.StatusCode.Should().Be(HttpStatusCode.OK);
+            var gallery = await response.Content.ReadFromJsonAsync<GalleryResult>();
+            gallery!.Page.Should().Be(1);
+            gallery.PageSize.Should().Be(12);
+        }
+
+        [Fact]
+        public async Task Gallery_WithInvalidPage_Returns400()
+        {
+            var response = await _client.GetAsync("/api/characters?page=0");
+
+            response.StatusCode.Should().Be(HttpStatusCode.BadRequest);
+        }
+
         private sealed record NameAvailabilityResult(bool Available);
+
+        private sealed record GalleryItem(
+            int Id,
+            string Name,
+            string ClassName,
+            string Gender,
+            string AuthorPseudo,
+            DateTime CreatedAt);
+
+        private sealed record GalleryResult(
+            IReadOnlyList<GalleryItem> Items,
+            int Page,
+            int PageSize,
+            int TotalCount,
+            int TotalPages);
     }
 }