feat(rules): redesign rules listing with server-side pagination, sorting, filtering, bulk actions, and table/card views

- Server-side paginated API: GET /api/v1/categorization-rules with search, category, status, sort params
- Bulk operations: POST activate/deactivate/delete for multiple rules
- New Blazor components: RulesTable, RulesToolbar, RulesPagination, BulkActionBar
- Table view with sortable columns, keyboard navigation (Arrow/Enter/Space/Esc)
- Card view toggle and group-by-category mode
- CategorizationEngine performance: rule caching, batch loading, string-first evaluation
- Contracts: CategorizationRuleListRequest, PageResponse, BulkRuleActionRequest/Response
- Comprehensive tests across Domain, Application, Infrastructure, API, and Client layers
- Performance regression tests for categorization engine (100 rules x 1000 transactions)

Refs: #115

Author: Fortinbra

docs/115-rules-listing-redesign.md

@@ -31,15 +31,51 @@ public CategorizationRulesController(ICategorizationRuleService service)
     }
 
     /// <summary>
-    /// Gets all categorization rules.
+    /// Gets categorization rules. When page/pageSize are provided, returns a paginated response.
+    /// Otherwise returns all rules for backward compatibility.
     /// </summary>
-    /// <param name="activeOnly">If true, returns only active rules.</param>
+    /// <param name="activeOnly">If true, returns only active rules (non-paginated mode only).</param>
+    /// <param name="page">Page number (1-based) for paginated results.</param>
+    /// <param name="pageSize">Number of items per page.</param>
+    /// <param name="search">Search text to filter by rule name or pattern.</param>
+    /// <param name="categoryId">Category ID to filter by.</param>
+    /// <param name="status">Status filter: "active", "inactive", or null for all.</param>
+    /// <param name="sortBy">Sort field: "priority", "name", "category", "createdAt".</param>
+    /// <param name="sortDirection">Sort direction: "asc" or "desc".</param>
     /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A list of categorization rules.</returns>
+    /// <returns>A list of categorization rules or a paged response.</returns>
     [HttpGet]
     [ProducesResponseType<IReadOnlyList<CategorizationRuleDto>>(StatusCodes.Status200OK)]
-    public async Task<IActionResult> GetAllAsync([FromQuery] bool activeOnly = false, CancellationToken cancellationToken = default)
+    [ProducesResponseType<CategorizationRulePageResponse>(StatusCodes.Status200OK)]
+    public async Task<IActionResult> GetAllAsync(
+        [FromQuery] bool activeOnly = false,
+        [FromQuery] int? page = null,
+        [FromQuery] int? pageSize = null,
+        [FromQuery] string? search = null,
+        [FromQuery] Guid? categoryId = null,
+        [FromQuery] string? status = null,
+        [FromQuery] string? sortBy = null,
+        [FromQuery] string? sortDirection = null,
+        CancellationToken cancellationToken = default)
     {
+        if (page.HasValue || pageSize.HasValue)
+        {
+            var request = new CategorizationRuleListRequest
+            {
+                Page = page ?? 1,
+                PageSize = pageSize ?? 25,
+                Search = search,
+                CategoryId = categoryId,
+                Status = status,
+                SortBy = sortBy,
+                SortDirection = sortDirection,
+            };
+
+            var pagedResult = await this._service.ListPagedAsync(request, cancellationToken);
+            this.Response.Headers["X-Pagination-TotalCount"] = pagedResult.TotalCount.ToString(System.Globalization.CultureInfo.InvariantCulture);
+            return this.Ok(pagedResult);
+        }
+
         var rules = await this._service.GetAllAsync(activeOnly, cancellationToken);
         return this.Ok(rules);
     }
@@ -222,4 +258,64 @@ public async Task<IActionResult> ApplyRulesAsync([FromBody] ApplyRulesRequest re
         var result = await this._service.ApplyRulesAsync(request, cancellationToken);
         return this.Ok(result);
     }
+
+    /// <summary>
+    /// Bulk deletes categorization rules.
+    /// </summary>
+    /// <param name="request">The bulk action request containing rule IDs.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The number of deleted rules.</returns>
+    [HttpDelete("bulk")]
+    [ProducesResponseType<BulkRuleActionResponse>(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    public async Task<IActionResult> BulkDeleteAsync([FromBody] BulkRuleActionRequest request, CancellationToken cancellationToken)
+    {
+        if (request.Ids.Count == 0)
+        {
+            return this.BadRequest("No rule IDs provided.");
+        }
+
+        var count = await this._service.BulkDeleteAsync(request.Ids, cancellationToken);
+        return this.Ok(new BulkRuleActionResponse { AffectedCount = count });
+    }
+
+    /// <summary>
+    /// Bulk activates categorization rules.
+    /// </summary>
+    /// <param name="request">The bulk action request containing rule IDs.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The number of activated rules.</returns>
+    [HttpPost("bulk/activate")]
+    [ProducesResponseType<BulkRuleActionResponse>(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    public async Task<IActionResult> BulkActivateAsync([FromBody] BulkRuleActionRequest request, CancellationToken cancellationToken)
+    {
+        if (request.Ids.Count == 0)
+        {
+            return this.BadRequest("No rule IDs provided.");
+        }
+
+        var count = await this._service.BulkActivateAsync(request.Ids, cancellationToken);
+        return this.Ok(new BulkRuleActionResponse { AffectedCount = count });
+    }
+
+    /// <summary>
+    /// Bulk deactivates categorization rules.
+    /// </summary>
+    /// <param name="request">The bulk action request containing rule IDs.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The number of deactivated rules.</returns>
+    [HttpPost("bulk/deactivate")]
+    [ProducesResponseType<BulkRuleActionResponse>(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    public async Task<IActionResult> BulkDeactivateAsync([FromBody] BulkRuleActionRequest request, CancellationToken cancellationToken)
+    {
+        if (request.Ids.Count == 0)
+        {
+            return this.BadRequest("No rule IDs provided.");
+        }
+
+        var count = await this._service.BulkDeactivateAsync(request.Ids, cancellationToken);
+        return this.Ok(new BulkRuleActionResponse { AffectedCount = count });
+    }
 }

src/BudgetExperiment.Api/Controllers/CategorizationRulesController.cs

@@ -5,31 +5,45 @@
 using BudgetExperiment.Contracts.Dtos;
 using BudgetExperiment.Domain;
 
+using Microsoft.Extensions.Caching.Memory;
+
 namespace BudgetExperiment.Application.Categorization;
 
 /// <summary>
 /// Implementation of <see cref="ICategorizationEngine"/> for applying auto-categorization rules to transactions.
+/// Uses batch transaction loading, in-memory rule caching, and string-first evaluation for performance.
 /// </summary>
 public class CategorizationEngine : ICategorizationEngine
 {
+    /// <summary>
+    /// Cache key for active rules ordered by priority.
+    /// </summary>
+    internal const string ActiveRulesCacheKey = "CategorizationEngine_ActiveRules";
+
+    private static readonly TimeSpan CacheDuration = TimeSpan.FromSeconds(30);
+
     private readonly ICategorizationRuleRepository _ruleRepository;
     private readonly ITransactionRepository _transactionRepository;
     private readonly IUnitOfWork _unitOfWork;
+    private readonly IMemoryCache _cache;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="CategorizationEngine"/> class.
     /// </summary>
     /// <param name="ruleRepository">The categorization rule repository.</param>
     /// <param name="transactionRepository">The transaction repository.</param>
     /// <param name="unitOfWork">The unit of work for persisting changes.</param>
+    /// <param name="cache">The memory cache for caching active rules.</param>
     public CategorizationEngine(
         ICategorizationRuleRepository ruleRepository,
         ITransactionRepository transactionRepository,
-        IUnitOfWork unitOfWork)
+        IUnitOfWork unitOfWork,
+        IMemoryCache cache)
     {
         this._ruleRepository = ruleRepository;
         this._transactionRepository = transactionRepository;
         this._unitOfWork = unitOfWork;
+        this._cache = cache;
     }
 
     /// <inheritdoc />
@@ -42,17 +56,8 @@ public CategorizationEngine(
             return null;
         }
 
-        var rules = await this._ruleRepository.GetActiveByPriorityAsync(cancellationToken);
-
-        foreach (var rule in rules)
-        {
-            if (rule.Matches(description))
-            {
-                return rule.CategoryId;
-            }
-        }
-
-        return null;
+        var rules = await this.GetCachedActiveRulesAsync(cancellationToken);
+        return FindFirstMatch(rules, description);
     }
 
     /// <inheritdoc />
@@ -61,7 +66,7 @@ public async Task<CategorizationResult> ApplyRulesAsync(
         bool overwriteExisting = false,
         CancellationToken cancellationToken = default)
     {
-        var rules = await this._ruleRepository.GetActiveByPriorityAsync(cancellationToken);
+        var rules = await this.GetCachedActiveRulesAsync(cancellationToken);
 
         var totalProcessed = 0;
         var categorized = 0;
@@ -74,50 +79,40 @@ public async Task<CategorizationResult> ApplyRulesAsync(
 
         if (transactionIds == null)
         {
-            // Process all uncategorized transactions
             transactions = await this._transactionRepository.GetUncategorizedAsync(cancellationToken);
         }
         else
         {
-            // Process specific transactions
+            var idList = transactionIds.ToList();
+            var allFetched = await this._transactionRepository.GetByIdsAsync(idList, cancellationToken);
+
             var transactionList = new List<Transaction>();
-            foreach (var id in transactionIds)
+            foreach (var transaction in allFetched)
             {
-                var transaction = await this._transactionRepository.GetByIdAsync(id, cancellationToken);
-                if (transaction != null)
+                if (overwriteExisting || transaction.CategoryId == null)
+                {
+                    transactionList.Add(transaction);
+                }
+                else
                 {
-                    // Skip already-categorized transactions unless overwriteExisting is true
-                    if (overwriteExisting || transaction.CategoryId == null)
-                    {
-                        transactionList.Add(transaction);
-                    }
-                    else
-                    {
-                        // Track as skipped due to existing category
-                        skippedDueToExisting++;
-                    }
+                    skippedDueToExisting++;
                 }
             }
 
             transactions = transactionList;
         }
 
+        // Partition rules: string rules first, then regex rules
+        var (stringRules, regexRules) = PartitionRules(rules);
+
         foreach (var transaction in transactions)
         {
             totalProcessed++;
 
             try
             {
-                Guid? matchedCategoryId = null;
-
-                foreach (var rule in rules)
-                {
-                    if (rule.Matches(transaction.Description))
-                    {
-                        matchedCategoryId = rule.CategoryId;
-                        break;
-                    }
-                }
+                var matchedCategoryId = FindFirstMatch(stringRules, transaction.Description)
+                    ?? FindFirstMatch(regexRules, transaction.Description);
 
                 if (matchedCategoryId.HasValue)
                 {
@@ -161,12 +156,11 @@ public async Task<IReadOnlyList<string>> TestPatternAsync(
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(pattern);
 
-        // Create a temporary rule to leverage the Matches logic
         var testRule = CategorizationRule.Create(
             name: "Test Rule",
             pattern: pattern,
             matchType: matchType,
-            categoryId: Guid.NewGuid(), // Dummy category, we just need the Matches method
+            categoryId: Guid.NewGuid(),
             caseSensitive: caseSensitive);
 
         var allDescriptions = await this._transactionRepository.GetAllDescriptionsAsync(cancellationToken);
@@ -208,35 +202,89 @@ public async Task<Dictionary<Guid, InlineCategorySuggestionDto>> GetBatchSuggest
             return result;
         }
 
-        var rules = await this._ruleRepository.GetActiveByPriorityAsync(cancellationToken);
+        var rules = await this.GetCachedActiveRulesAsync(cancellationToken);
         if (rules.Count == 0)
         {
             return result;
         }
 
-        foreach (var transactionId in transactionIds)
+        var transactions = await this._transactionRepository.GetByIdsAsync(transactionIds, cancellationToken);
+
+        foreach (var transaction in transactions)
         {
-            var transaction = await this._transactionRepository.GetByIdAsync(transactionId, cancellationToken);
-            if (transaction is null || transaction.CategoryId is not null)
+            if (transaction.CategoryId is not null)
             {
                 continue;
             }
 
-            foreach (var rule in rules)
+            var matchedCategoryId = FindFirstMatch(rules, transaction.Description);
+            if (matchedCategoryId.HasValue)
             {
-                if (rule.Matches(transaction.Description))
+                var matchedRule = rules.First(r => r.CategoryId == matchedCategoryId.Value && r.Matches(transaction.Description));
+                result[transaction.Id] = new InlineCategorySuggestionDto
                 {
-                    result[transactionId] = new InlineCategorySuggestionDto
-                    {
-                        TransactionId = transactionId,
-                        CategoryId = rule.CategoryId,
-                        CategoryName = rule.Category?.Name ?? string.Empty,
-                    };
-                    break;
-                }
+                    TransactionId = transaction.Id,
+                    CategoryId = matchedCategoryId.Value,
+                    CategoryName = matchedRule.Category?.Name ?? string.Empty,
+                };
             }
         }
 
         return result;
     }
+
+    /// <summary>
+    /// Invalidates the cached active rules, forcing a fresh load on next access.
+    /// Called by <see cref="CategorizationRuleService"/> after rule CRUD operations.
+    /// </summary>
+    public void InvalidateRuleCache()
+    {
+        this._cache.Remove(ActiveRulesCacheKey);
+    }
+
+    private static Guid? FindFirstMatch(IReadOnlyList<CategorizationRule> rules, string description)
+    {
+        foreach (var rule in rules)
+        {
+            if (rule.Matches(description))
+            {
+                return rule.CategoryId;
+            }
+        }
+
+        return null;
+    }
+
+    private static (IReadOnlyList<CategorizationRule> StringRules, IReadOnlyList<CategorizationRule> RegexRules) PartitionRules(
+        IReadOnlyList<CategorizationRule> rules)
+    {
+        var stringRules = new List<CategorizationRule>();
+        var regexRules = new List<CategorizationRule>();
+
+        foreach (var rule in rules)
+        {
+            if (rule.MatchType == RuleMatchType.Regex)
+            {
+                regexRules.Add(rule);
+            }
+            else
+            {
+                stringRules.Add(rule);
+            }
+        }
+
+        return (stringRules, regexRules);
+    }
+
+    private async Task<IReadOnlyList<CategorizationRule>> GetCachedActiveRulesAsync(CancellationToken cancellationToken)
+    {
+        if (this._cache.TryGetValue(ActiveRulesCacheKey, out IReadOnlyList<CategorizationRule>? cached) && cached is not null)
+        {
+            return cached;
+        }
+
+        var rules = await this._ruleRepository.GetActiveByPriorityAsync(cancellationToken);
+        this._cache.Set(ActiveRulesCacheKey, rules, CacheDuration);
+        return rules;
+    }
 }