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/Infrastructure/Infrastructure.Sql/DependencyInjection/InfrastructureSqlServiceCollectionExtensions.cs

@@ -0,0 +1,15 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Infrastructure.Sql.DependencyInjection;
+
+/// <summary>Extension methods for registering SQL infrastructure services with dependency injection.</summary>
+public static class InfrastructureSqlServiceCollectionExtensions
+{
+    /// <summary>Registers <see cref="DefaultSqlConnectionFactory" /> as a singleton <see cref="ISqlConnectionFactory" />.</summary>
+    /// <returns>The same <paramref name="services" /> instance, for chaining.</returns>
+    public static IServiceCollection AddInfrastructureSql(this IServiceCollection services)
+    {
+        services.AddSingleton<ISqlConnectionFactory, DefaultSqlConnectionFactory>();
+        return services;
+    }
+}

web/backend/Infrastructure/Infrastructure.Sql/Infrastructure.Sql.csproj

@@ -6,12 +6,16 @@
         <RootNamespace>Infrastructure.Sql</RootNamespace>
     </PropertyGroup>
     <ItemGroup>
+        <PackageReference Include="Dapper" Version="2.1.79" />
         <PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.2" />
         <PackageReference Include="Microsoft.SqlServer.Types" Version="160.1000.6" />
-        <PackageReference Include="System.Data.SqlClient" Version="4.9.0" />
         <PackageReference
             Include="Microsoft.Extensions.Configuration.Abstractions"
             Version="9.0.0"
         />
+        <PackageReference
+            Include="Microsoft.Extensions.DependencyInjection.Abstractions"
+            Version="10.0.0"
+        />
     </ItemGroup>
 </Project>

web/backend/Infrastructure/Infrastructure.Sql/Repository.cs

@@ -3,8 +3,8 @@ using System.Data.Common;
 namespace Infrastructure.Sql;
 
 /// <summary>
-///     Base class for ADO.NET-based repositories, providing shared connection creation and
-///     entity-mapping infrastructure for derived repository implementations.
+///     Base class for Dapper-based repositories, providing shared connection creation for derived
+///     repository implementations.
 /// </summary>
 public abstract class Repository<T>(ISqlConnectionFactory connectionFactory)
     where T : class
@@ -19,9 +19,4 @@ public abstract class Repository<T>(ISqlConnectionFactory connectionFactory)
         await connection.OpenAsync();
         return connection;
     }
-
-    /// <summary>
-    ///     Maps the current row of a data reader to an instance of <typeparamref name="T" />.
-    /// </summary>
-    protected abstract T MapToEntity(DbDataReader reader);
 }

web/backend/Infrastructure/Infrastructure.Sql/SqlConnectionStringHelper.cs

@@ -14,22 +14,10 @@ public static class SqlConnectionStringHelper
     /// <param name="databaseName">If null, falls back to the DB_NAME environment variable.</param>
     public static string BuildConnectionString(string? databaseName = null)
     {
-        string server =
-            Environment.GetEnvironmentVariable("DB_SERVER")
-            ?? throw new InvalidOperationException("DB_SERVER environment variable is not set");
-
-        string dbName =
-            databaseName
-            ?? Environment.GetEnvironmentVariable("DB_NAME")
-            ?? throw new InvalidOperationException("DB_NAME environment variable is not set");
-
-        string user =
-            Environment.GetEnvironmentVariable("DB_USER")
-            ?? throw new InvalidOperationException("DB_USER environment variable is not set");
-
-        string password =
-            Environment.GetEnvironmentVariable("DB_PASSWORD")
-            ?? throw new InvalidOperationException("DB_PASSWORD environment variable is not set");
+        string server = Required("DB_SERVER");
+        string dbName = databaseName ?? Required("DB_NAME");
+        string user = Required("DB_USER");
+        string password = Required("DB_PASSWORD");
 
         SqlConnectionStringBuilder builder = new()
         {
@@ -37,7 +25,7 @@ public static class SqlConnectionStringHelper
             InitialCatalog = dbName,
             UserID = user,
             Password = password,
-            TrustServerCertificate = true,
+            TrustServerCertificate = ResolveTrustServerCertificate(),
             Encrypt = true,
         };
 
@@ -51,4 +39,23 @@ public static class SqlConnectionStringHelper
     {
         return BuildConnectionString("master");
     }
+
+    /// <summary>
+    ///     Resolves the <c>DB_TRUST_SERVER_CERTIFICATE</c> environment variable, defaulting to
+    ///     <c>true</c> when it is unset or not a valid boolean.
+    /// </summary>
+    private static bool ResolveTrustServerCertificate()
+    {
+        return !bool.TryParse(
+                Environment.GetEnvironmentVariable("DB_TRUST_SERVER_CERTIFICATE"),
+                out bool trustServerCertificate
+            )
+            || trustServerCertificate;
+    }
+
+    private static string Required(string variableName) =>
+        Environment.GetEnvironmentVariable(variableName)
+        ?? throw new InvalidOperationException(
+            $"The {variableName} environment variable is not set."
+        );
 }

web/backend/Infrastructure/Infrastructure.Sql/SqlErrorCodes.cs

@@ -0,0 +1,44 @@
+namespace Infrastructure.Sql;
+
+/// <summary>
+///     Custom SQL Server error numbers (50000+) that a stored procedure could use to signal
+///     domain-level failures via <c>THROW</c>, for a repository to catch as
+///     <see cref="Microsoft.Data.SqlClient.SqlException" /> and translate via <c>ex.Number</c> into
+///     the corresponding <c>Domain.Exceptions</c> type.
+/// </summary>
+/// <remarks>
+///     Currently unused: the schema has no stored procedures, and no repository throws or catches on
+///     these numbers. Repositories instead run their own existence/concurrency checks and throw
+///     <c>Domain.Exceptions</c> directly (see <c>docs/website/database.md</c> for the current
+///     approach). This type is kept in case a future stored procedure reintroduces the pattern; each
+///     number would
+///     identify a category of error shared by every procedure that raises it, not a single call site.
+/// </remarks>
+public static class SqlErrorCodes
+{
+    /// <summary>
+    ///     A stored procedure's own input validation failed (e.g. a required parameter was <c>NULL</c>).
+    ///     Maps to HTTP 400 Bad Request.
+    /// </summary>
+    public const int Validation = 50400;
+
+    /// <summary>
+    ///     A stored procedure could not find a row it required, by primary key or foreign key. Maps to
+    ///     HTTP 404 Not Found.
+    /// </summary>
+    public const int NotFound = 50404;
+
+    /// <summary>
+    ///     A stored procedure detected a conflict: either a duplicate/already-exists row, or a stale
+    ///     optimistic-concurrency token (row-version mismatch). Maps to HTTP 409 Conflict.
+    /// </summary>
+    public const int Conflict = 50409;
+
+    /// <summary>
+    ///     A defensive check inside a stored procedure failed under conditions that should be
+    ///     unreachable in normal operation (e.g. an <c>INSERT</c> that should always affect one row
+    ///     affected zero). Left uncaught by repositories so it falls through to the generic
+    ///     <see cref="Microsoft.Data.SqlClient.SqlException" /> handler. Maps to HTTP 500/503.
+    /// </summary>
+    public const int InternalFailure = 50500;
+}