refactor(infrastructure): extract timestamp update logic and implement lead repository

- Extract UpdateModifiedLeadTimestamps() method to eliminate DRY violation
  * Caches dateTimeProvider.UtcNow once to ensure transactional consistency
  * All modified entities in same transaction receive identical timestamp
  * Improves performance with early exit when no entities modified
  * Single source of truth for timestamp update logic

- Implement LeadRepository with EF Core
  * SaveLeadAsync: Handles insert/update with automatic timestamp management
  * ExistsByCorrelationIdAsync: Optimized query for idempotency checks
  * GetByCorrelationIdAsync: Efficient correlation ID lookups
  * Automatic EF Core tracking conflict resolution
  * Full cancellation token support
  * Comprehensive input validation and exception handling

- All 24 repository tests passing
- All 9 DbContext tests passing (no regressions)
- 175 total tests passing (100% pass rate)
- Zero build warnings/errors

This completes Step 4.3 and prepares infrastructure for Step 4.4 configuration settings.

Author: sl-cloud

src/LeadProcessor.Infrastructure/Persistence/LeadProcessorDbContext.cs

@@ -120,18 +120,7 @@ protected override void OnModelCreating(ModelBuilder modelBuilder)
     /// </remarks>
     public override async Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
     {
-        var modifiedLeadEntries = ChangeTracker.Entries<Lead>()
-            .Where(e => e.State == EntityState.Modified)
-            .ToList();
-
-        foreach (var entry in modifiedLeadEntries)
-        {
-            // Create a new Lead instance with the updated timestamp
-            // This is required because Lead is a record type (immutable)
-            var updatedLead = entry.Entity with { UpdatedAt = dateTimeProvider.UtcNow };
-            entry.CurrentValues.SetValues(updatedLead);
-        }
-
+        UpdateModifiedLeadTimestamps();
         return await base.SaveChangesAsync(cancellationToken);
     }
 
@@ -144,18 +133,41 @@ public override async Task<int> SaveChangesAsync(CancellationToken cancellationT
     /// This synchronous method is provided for compatibility but async methods should be preferred.
     /// </remarks>
     public override int SaveChanges(bool acceptAllChangesOnSuccess)
+    {
+        UpdateModifiedLeadTimestamps();
+        return base.SaveChanges(acceptAllChangesOnSuccess);
+    }
+
+    /// <summary>
+    /// Updates the UpdatedAt timestamp for all modified Lead entities in the change tracker.
+    /// </summary>
+    /// <remarks>
+    /// This method caches the current UTC time once to ensure all modified entities
+    /// in the same transaction receive the exact same timestamp, maintaining transactional consistency.
+    /// The timestamp update is required to maintain immutability of record types while ensuring audit trail accuracy.
+    /// </remarks>
+    private void UpdateModifiedLeadTimestamps()
     {
         var modifiedLeadEntries = ChangeTracker.Entries<Lead>()
             .Where(e => e.State == EntityState.Modified)
             .ToList();
 
+        if (modifiedLeadEntries.Count == 0)
+        {
+            return;
+        }
+
+        // Cache the timestamp once to ensure all entities get the same value
+        // This maintains transactional consistency
+        var updateTimestamp = dateTimeProvider.UtcNow;
+
         foreach (var entry in modifiedLeadEntries)
         {
-            var updatedLead = entry.Entity with { UpdatedAt = dateTimeProvider.UtcNow };
+            // Create a new Lead instance with the updated timestamp
+            // This is required because Lead is a record type (immutable)
+            var updatedLead = entry.Entity with { UpdatedAt = updateTimestamp };
             entry.CurrentValues.SetValues(updatedLead);
         }
-
-        return base.SaveChanges(acceptAllChangesOnSuccess);
     }
 }
 

src/LeadProcessor.Infrastructure/Repositories/LeadRepository.cs

@@ -0,0 +1,109 @@
+using LeadProcessor.Domain.Entities;
+using LeadProcessor.Domain.Repositories;
+using LeadProcessor.Infrastructure.Persistence;
+using Microsoft.EntityFrameworkCore;
+
+namespace LeadProcessor.Infrastructure.Repositories;
+
+/// <summary>
+/// EF Core implementation of <see cref="ILeadRepository"/> for managing lead persistence operations.
+/// </summary>
+/// <remarks>
+/// This repository provides data access operations for the Lead entity using Entity Framework Core.
+/// All operations are async and support cancellation tokens for graceful shutdown.
+/// Thread-safe when used with proper DbContext lifecycle management (scoped per request).
+/// </remarks>
+/// <param name="context">The database context for lead operations.</param>
+public sealed class LeadRepository(LeadProcessorDbContext context) : ILeadRepository
+{
+    private readonly LeadProcessorDbContext _context = context ?? throw new ArgumentNullException(nameof(context));
+
+    /// <summary>
+    /// Saves a lead to the data store asynchronously.
+    /// </summary>
+    /// <param name="lead">The lead entity to save.</param>
+    /// <param name="cancellationToken">Cancellation token to cancel the operation.</param>
+    /// <returns>The saved lead entity with updated fields (e.g., Id, timestamps).</returns>
+    /// <exception cref="ArgumentNullException">Thrown when lead is null.</exception>
+    /// <exception cref="DbUpdateException">Thrown when a database update error occurs.</exception>
+    /// <remarks>
+    /// This method handles both insert and update operations:
+    /// - For new leads (Id == 0), performs an INSERT
+    /// - For existing leads (Id > 0), performs an UPDATE
+    /// The UpdatedAt timestamp is automatically updated by the DbContext on save.
+    /// For updates, detaches any tracked entity to prevent tracking conflicts.
+    /// </remarks>
+    public async Task<Lead> SaveLeadAsync(Lead lead, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(lead);
+
+        // Determine if this is a new entity or an existing one
+        if (lead.Id == 0)
+        {
+            // New entity - add to context for insert
+            await _context.Leads.AddAsync(lead, cancellationToken);
+        }
+        else
+        {
+            // Existing entity - check if it's already tracked
+            var trackedEntity = _context.Leads.Local.FirstOrDefault(l => l.Id == lead.Id);
+            if (trackedEntity != null)
+            {
+                // Detach the tracked entity to avoid conflicts
+                _context.Entry(trackedEntity).State = EntityState.Detached;
+            }
+
+            // Attach and mark as modified for update
+            _context.Leads.Update(lead);
+        }
+
+        await _context.SaveChangesAsync(cancellationToken);
+        return lead;
+    }
+
+    /// <summary>
+    /// Checks if a lead with the specified correlation ID already exists.
+    /// This method supports idempotency by allowing duplicate message detection.
+    /// </summary>
+    /// <param name="correlationId">The correlation ID to check for.</param>
+    /// <param name="cancellationToken">Cancellation token to cancel the operation.</param>
+    /// <returns>True if a lead with the correlation ID exists, otherwise false.</returns>
+    /// <exception cref="ArgumentException">Thrown when correlationId is null or whitespace.</exception>
+    /// <remarks>
+    /// This method uses an optimized query that only checks for existence without loading the entity.
+    /// It leverages the indexed CorrelationId column for fast lookups.
+    /// </remarks>
+    public async Task<bool> ExistsByCorrelationIdAsync(string correlationId, CancellationToken cancellationToken = default)
+    {
+        if (string.IsNullOrWhiteSpace(correlationId))
+        {
+            throw new ArgumentException("Correlation ID cannot be null or whitespace.", nameof(correlationId));
+        }
+
+        return await _context.Leads
+            .AnyAsync(l => l.CorrelationId == correlationId, cancellationToken);
+    }
+
+    /// <summary>
+    /// Retrieves a lead by its correlation ID asynchronously.
+    /// </summary>
+    /// <param name="correlationId">The correlation ID to search for.</param>
+    /// <param name="cancellationToken">Cancellation token to cancel the operation.</param>
+    /// <returns>The lead entity if found, otherwise null.</returns>
+    /// <exception cref="ArgumentException">Thrown when correlationId is null or whitespace.</exception>
+    /// <remarks>
+    /// This method leverages the indexed CorrelationId column for efficient lookups.
+    /// Returns null if no lead is found with the specified correlation ID.
+    /// </remarks>
+    public async Task<Lead?> GetByCorrelationIdAsync(string correlationId, CancellationToken cancellationToken = default)
+    {
+        if (string.IsNullOrWhiteSpace(correlationId))
+        {
+            throw new ArgumentException("Correlation ID cannot be null or whitespace.", nameof(correlationId));
+        }
+
+        return await _context.Leads
+            .FirstOrDefaultAsync(l => l.CorrelationId == correlationId, cancellationToken);
+    }
+}
+