Implement player profile creation flow and profile page (#211, #213)

Adds the full player profile feature: first-visit onboarding gate,
persistent UserProfile aggregate in CosmosDB, silent migration of
legacy alias-only users, and /profile page with alias editing for
both React and Blazor frontends.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: xenobiasoft

infra/modules/storage.bicep

@@ -229,6 +229,46 @@ resource gamesThroughput 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/con
   }
 }
 
+resource profilesContainer 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15' = {
+  parent: sudokuDatabase
+  name: 'profiles'
+  properties: {
+    resource: {
+      id: 'profiles'
+      partitionKey: {
+        paths: ['/alias']
+        kind: 'Hash'
+        version: 2
+      }
+      indexingPolicy: {
+        indexingMode: 'consistent'
+        automatic: true
+        includedPaths: [{ path: '/*' }]
+        excludedPaths: [{ path: '/"_etag"/?' }]
+      }
+      uniqueKeyPolicy: {
+        uniqueKeys: [
+          { paths: ['/alias'] }
+        ]
+      }
+      conflictResolutionPolicy: {
+        mode: 'LastWriterWins'
+        conflictResolutionPath: '/_ts'
+      }
+    }
+  }
+}
+
+resource profilesThroughput 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/throughputSettings@2024-05-15' = {
+  parent: profilesContainer
+  name: 'default'
+  properties: {
+    resource: {
+      throughput: 400
+    }
+  }
+}
+
 output storageAccountId string = storageAccount.id
 output storageAccountName string = storageAccount.name
 output cosmosDbAccountId string = cosmosDbAccount.id

src/backend/Sudoku.Api/Controllers/ProfilesController.cs

@@ -0,0 +1,75 @@
+using MediatR;
+using Microsoft.AspNetCore.Mvc;
+using Sudoku.Api.Models;
+using Sudoku.Application.Commands;
+using Sudoku.Application.DTOs;
+using Sudoku.Application.Queries;
+
+namespace Sudoku.Api.Controllers;
+
+[Route("api/profiles")]
+[ApiController]
+public class ProfilesController(IMediator mediator) : ControllerBase
+{
+    [HttpPost]
+    [ProducesResponseType(typeof(ProfileDto), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status409Conflict)]
+    public async Task<ActionResult<ProfileDto>> CreateProfileAsync([FromBody] CreateProfileRequest request)
+    {
+        var result = await mediator.Send(new CreateProfileCommand(request.Alias));
+
+        if (!result.IsSuccess)
+        {
+            if (result.Error!.Contains("already taken", StringComparison.OrdinalIgnoreCase))
+                return Conflict(result.Error);
+            return BadRequest(result.Error);
+        }
+
+        return StatusCode(StatusCodes.Status201Created, result.Value);
+    }
+
+    [HttpGet("{alias}")]
+    [ProducesResponseType(typeof(ProfileDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<ActionResult<ProfileDto>> GetProfileAsync(string alias)
+    {
+        var result = await mediator.Send(new GetProfileByAliasQuery(alias));
+
+        if (!result.IsSuccess)
+            return BadRequest(result.Error);
+
+        if (result.Value == null)
+            return NotFound();
+
+        return Ok(result.Value);
+    }
+
+    [HttpPatch("{alias}")]
+    [ProducesResponseType(typeof(ProfileDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status409Conflict)]
+    public async Task<ActionResult<ProfileDto>> UpdateProfileAliasAsync(string alias, [FromBody] UpdateProfileAliasRequest request)
+    {
+        // First resolve the profile by alias to get profileId
+        var getResult = await mediator.Send(new GetProfileByAliasQuery(alias));
+        if (!getResult.IsSuccess)
+            return BadRequest(getResult.Error);
+        if (getResult.Value == null)
+            return NotFound();
+
+        var updateResult = await mediator.Send(new UpdateProfileAliasCommand(getResult.Value.ProfileId, request.NewAlias));
+
+        if (!updateResult.IsSuccess)
+        {
+            if (updateResult.Error!.Contains("already taken", StringComparison.OrdinalIgnoreCase))
+                return Conflict(updateResult.Error);
+            if (updateResult.Error.Contains("not found", StringComparison.OrdinalIgnoreCase))
+                return NotFound();
+            return BadRequest(updateResult.Error);
+        }
+
+        return Ok(updateResult.Value);
+    }
+}

src/backend/Sudoku.Api/Models/CreateProfileRequest.cs

@@ -0,0 +1,5 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace Sudoku.Api.Models;
+
+public record CreateProfileRequest([Required] string Alias);

src/backend/Sudoku.Api/Models/UpdateProfileAliasRequest.cs

@@ -0,0 +1,5 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace Sudoku.Api.Models;
+
+public record UpdateProfileAliasRequest([Required] string NewAlias);

src/backend/Sudoku.Application/Commands/CreateProfileCommand.cs

@@ -0,0 +1,6 @@
+using Sudoku.Application.Common;
+using Sudoku.Application.DTOs;
+
+namespace Sudoku.Application.Commands;
+
+public record CreateProfileCommand(string Alias) : ICommand<ProfileDto>;

src/backend/Sudoku.Application/Commands/UpdateProfileAliasCommand.cs

@@ -0,0 +1,6 @@
+using Sudoku.Application.Common;
+using Sudoku.Application.DTOs;
+
+namespace Sudoku.Application.Commands;
+
+public record UpdateProfileAliasCommand(string ProfileId, string NewAlias) : ICommand<ProfileDto>;

src/backend/Sudoku.Application/Common/ICommandOfT.cs

@@ -0,0 +1,8 @@
+using MediatR;
+
+namespace Sudoku.Application.Common;
+
+public interface ICommand<TResult> : IRequest<Result<TResult>> {}
+
+public interface ICommandHandler<in TCommand, TResult> : IRequestHandler<TCommand, Result<TResult>>
+    where TCommand : ICommand<TResult> {}

src/backend/Sudoku.Application/DTOs/ProfileDto.cs

@@ -0,0 +1,9 @@
+using Sudoku.Domain.Entities;
+
+namespace Sudoku.Application.DTOs;
+
+public record ProfileDto(string ProfileId, string Alias, DateTime CreatedAt, DateTime UpdatedAt)
+{
+    public static ProfileDto FromProfile(UserProfile profile) =>
+        new(profile.Id.ToString(), profile.Alias.Value, profile.CreatedAt, profile.UpdatedAt);
+}

src/backend/Sudoku.Application/Handlers/CreateProfileCommandHandler.cs

@@ -0,0 +1,45 @@
+using Microsoft.Extensions.Logging;
+using Sudoku.Application.Commands;
+using Sudoku.Application.Common;
+using Sudoku.Application.DTOs;
+using Sudoku.Application.Interfaces;
+using Sudoku.Domain.Exceptions;
+using Sudoku.Domain.ValueObjects;
+
+namespace Sudoku.Application.Handlers;
+
+public class CreateProfileCommandHandler(
+    IUserProfileRepository profileRepository,
+    ILogger<CreateProfileCommandHandler> logger) : ICommandHandler<CreateProfileCommand, ProfileDto>
+{
+    public async Task<Result<ProfileDto>> Handle(CreateProfileCommand request, CancellationToken cancellationToken)
+    {
+        try
+        {
+            var normalizedAlias = request.Alias.Trim().ToLowerInvariant();
+            var playerAlias = PlayerAlias.Create(normalizedAlias);
+
+            if (await profileRepository.AliasExistsAsync(playerAlias))
+            {
+                logger.LogWarning("Alias already taken: {Alias}", playerAlias.Value);
+                return Result<ProfileDto>.Failure($"Alias '{playerAlias.Value}' is already taken.");
+            }
+
+            var profile = Domain.Entities.UserProfile.Create(playerAlias);
+            await profileRepository.SaveAsync(profile);
+
+            logger.LogInformation("Created profile {ProfileId} for alias {Alias}", profile.Id, playerAlias.Value);
+            return Result<ProfileDto>.Success(ProfileDto.FromProfile(profile));
+        }
+        catch (DomainException ex)
+        {
+            logger.LogWarning("Domain error creating profile: {Error}", ex.Message);
+            return Result<ProfileDto>.Failure(ex.Message);
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Unexpected error creating profile for alias {Alias}", request.Alias);
+            return Result<ProfileDto>.Failure($"An unexpected error occurred: {ex.Message}");
+        }
+    }
+}

src/backend/Sudoku.Application/Handlers/GetProfileByAliasQueryHandler.cs

@@ -0,0 +1,43 @@
+using Microsoft.Extensions.Logging;
+using Sudoku.Application.Common;
+using Sudoku.Application.DTOs;
+using Sudoku.Application.Interfaces;
+using Sudoku.Application.Queries;
+using Sudoku.Domain.Exceptions;
+using Sudoku.Domain.ValueObjects;
+
+namespace Sudoku.Application.Handlers;
+
+public class GetProfileByAliasQueryHandler(
+    IUserProfileRepository profileRepository,
+    ILogger<GetProfileByAliasQueryHandler> logger) : IQueryHandler<GetProfileByAliasQuery, ProfileDto?>
+{
+    public async Task<Result<ProfileDto?>> Handle(GetProfileByAliasQuery request, CancellationToken cancellationToken)
+    {
+        try
+        {
+            var normalizedAlias = request.Alias.Trim().ToLowerInvariant();
+            var playerAlias = PlayerAlias.Create(normalizedAlias);
+            var profile = await profileRepository.GetByAliasAsync(playerAlias);
+
+            if (profile == null)
+            {
+                logger.LogDebug("Profile not found for alias {Alias}", playerAlias.Value);
+                return Result<ProfileDto?>.Success(null);
+            }
+
+            logger.LogDebug("Retrieved profile {ProfileId} for alias {Alias}", profile.Id, playerAlias.Value);
+            return Result<ProfileDto?>.Success(ProfileDto.FromProfile(profile));
+        }
+        catch (DomainException ex)
+        {
+            logger.LogWarning("Domain error getting profile for alias {Alias}: {Error}", request.Alias, ex.Message);
+            return Result<ProfileDto?>.Failure(ex.Message);
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Unexpected error getting profile for alias {Alias}", request.Alias);
+            return Result<ProfileDto?>.Failure($"An unexpected error occurred: {ex.Message}");
+        }
+    }
+}