Migrate Auth/Brewery/Location repositories to pure Dapper; rename Timer to RowVersion (#237)

* Integrate Spectre.Console into seed application, use async data loading

* Replace stored-procedure repositories with Dapper-based repositories

Removes the USP_* stored procedures for Auth, Location, and Brewery
data access in favour of services built with Dapper.

Adds a new Features.Locations slice and optimistic concurrency support
for the Brewery slice.

* Add new documentation for Dapper migration/database schema

* Update FluentAssertions to most recent open source ver

* Update XML doc comment in backend projects

* Modify brewery location dto to include denormalized data

* - Updated column names from 'Timer' to 'RowVersion' in schema.sql for
- Introduced new BeerPost entity and updated BreweryPost and BreweryPostLocation entities to use 'RowVersion' for concurrency.
- Modified UserAccount, UserCredential, UserVerification, City, StateProvince, and Country entities to use 'RowVersion' instead of 'Timer'.
- Updated tests and command handlers to reflect changes in concurrency token from 'Timer' to 'RowVersion'.
- Adjusted BreweryDto and BreweryDtoMapper to include 'RowVersion' and updated mapping logic accordingly.
- Ensured all repository methods and interfaces are aligned with the new concurrency handling approach.

* updates

* Add BeerStyle entity and related properties; refactor BreweryDto to remove BeerPosts

* Fix Api.Specs test failures: stale Timer column refs and missing test.user fixture

* Remove repository tests, usages of registration dto used in repo

* archive old stored procs/functions

* update stale docs

* Add instructions for generating cryptographically secure base64 secrets on macOS/Linux and Windows

web/backend/Features/Features.Auth/Commands/Login/LoginCommand.cs

@@ -0,0 +1,10 @@
+using Features.Auth.Dtos;
+using MediatR;
+
+namespace Features.Auth.Commands.Login;
+
+/// <summary>
+///     Authenticates a user using their username and password and issues new tokens. Bound directly
+///     from the request body of <c>POST /api/auth/login</c>.
+/// </summary>
+public record LoginCommand(string Username, string Password) : IRequest<LoginPayload>;

web/backend/Features/Features.Auth/Commands/Login/LoginHandler.cs

@@ -0,0 +1,43 @@
+using Domain.Entities;
+using Domain.Exceptions;
+using Features.Auth.Dtos;
+using Features.Auth.Repository;
+using Features.Auth.Services;
+using Infrastructure.PasswordHashing;
+using MediatR;
+
+namespace Features.Auth.Commands.Login;
+
+/// <summary>
+///     Handles <see cref="LoginCommand" /> by verifying credentials and issuing access/refresh tokens.
+/// </summary>
+public class LoginHandler(
+    IAuthRepository authRepo,
+    IPasswordInfrastructure passwordInfrastructure,
+    ITokenService tokenService
+) : IRequestHandler<LoginCommand, LoginPayload>
+{
+    /// <exception cref="UnauthorizedException">
+    ///     Thrown when the username does not match any account, the account has no active credential,
+    ///     or the supplied password does not match the stored hash.
+    /// </exception>
+    public async Task<LoginPayload> Handle(LoginCommand request, CancellationToken cancellationToken)
+    {
+        UserAccount user =
+            await authRepo.GetUserByUsernameAsync(request.Username)
+            ?? throw new UnauthorizedException("Invalid username or password.");
+
+        // @todo handle expired passwords
+        UserCredential activeCred =
+            await authRepo.GetActiveCredentialByUserAccountIdAsync(user.UserAccountId)
+            ?? throw new UnauthorizedException("Invalid username or password.");
+
+        if (!passwordInfrastructure.Verify(request.Password, activeCred.Hash))
+            throw new UnauthorizedException("Invalid username or password.");
+
+        string accessToken = tokenService.GenerateAccessToken(user);
+        string refreshToken = tokenService.GenerateRefreshToken(user);
+
+        return new LoginPayload(user.UserAccountId, user.Username, refreshToken, accessToken);
+    }
+}

web/backend/Features/Features.Auth/Commands/Login/LoginValidator.cs

@@ -0,0 +1,14 @@
+using FluentValidation;
+
+namespace Features.Auth.Commands.Login;
+
+/// <summary>Validates that <see cref="LoginCommand.Username" /> and <see cref="LoginCommand.Password" /> are present.</summary>
+public class LoginValidator : AbstractValidator<LoginCommand>
+{
+    public LoginValidator()
+    {
+        RuleFor(x => x.Username).NotEmpty().WithMessage("Username is required");
+
+        RuleFor(x => x.Password).NotEmpty().WithMessage("Password is required");
+    }
+}

web/backend/Features/Features.Auth/Commands/RefreshToken/RefreshTokenHandler.cs

@@ -11,6 +11,10 @@ namespace Features.Auth.Commands.RefreshToken;
 public class RefreshTokenHandler(ITokenService tokenService)
     : IRequestHandler<RefreshTokenCommand, LoginPayload>
 {
+    /// <exception cref="Domain.Exceptions.UnauthorizedException">
+    ///     Thrown when the refresh token is invalid or expired, or when the user account it refers to no
+    ///     longer exists.
+    /// </exception>
     public async Task<LoginPayload> Handle(
         RefreshTokenCommand request,
         CancellationToken cancellationToken

web/backend/Features/Features.Auth/Commands/RefreshToken/RefreshTokenValidator.cs

@@ -2,6 +2,7 @@ using FluentValidation;
 
 namespace Features.Auth.Commands.RefreshToken;
 
+/// <summary>Validates that <see cref="RefreshTokenCommand.RefreshToken" /> is present.</summary>
 public class RefreshTokenValidator : AbstractValidator<RefreshTokenCommand>
 {
     public RefreshTokenValidator()

web/backend/Features/Features.Auth/Commands/RegisterUser/RegisterUserHandler.cs

@@ -34,14 +34,18 @@ public class RegisterUserHandler(
         string hashed = passwordInfrastructure.Hash(request.Password);
 
         UserAccount createdUser = await authRepo.RegisterUserAsync(
-            new UserRegistrationDto(
-                request.Username,
-                request.FirstName,
-                request.LastName,
-                request.Email,
-                request.DateOfBirth,
-                hashed
-            )
+            new UserAccount
+            {
+                Username = request.Username,
+                FirstName =  request.FirstName,
+                LastName =  request.LastName,
+                DateOfBirth =  request.DateOfBirth,
+                Email = request.Email,
+                UserCredential = new UserCredential
+                {
+                    Hash = hashed,
+                }
+            }
         );
 
         string accessToken = tokenService.GenerateAccessToken(createdUser);

web/backend/Features/Features.Auth/Commands/RegisterUser/RegisterUserValidator.cs

@@ -2,6 +2,10 @@ using FluentValidation;
 
 namespace Features.Auth.Commands.RegisterUser;
 
+/// <summary>
+///     Validates the field-level constraints on <see cref="RegisterUserCommand" />: username format and
+///     length, name lengths, email format, minimum age of 19, and password complexity.
+/// </summary>
 public class RegisterUserValidator : AbstractValidator<RegisterUserCommand>
 {
     public RegisterUserValidator()