feat: Enhance sales management with new scheduling and editing dialogs, improved SSE handling, and updated query invalidation rules

Author: aalmada

AGENTS.md

@@ -95,7 +95,7 @@ dotnet test -- --treenode-filter "/*/*/*/*[Category=Integration]"
 ## Common Mistakes
 
 - Business logic in endpoints -> put it in aggregates/handlers
-- Missing SSE notification -> add to `MartenCommitListener`
+- Missing SSE notification -> add handler in `ProjectionCommitListener` (API) AND add query key in `QueryInvalidationService` (Web)
 - Missing cache invalidation -> call `RemoveByTagAsync` after mutations
 
 ## Quick Troubleshooting

src/BookStore.ApiService/AGENTS.md

@@ -28,12 +28,13 @@
 
 ## Common Mistakes
 - ❌ Business logic in endpoints → Put logic in aggregates/handlers
-- ❌ Missing SSE notification → Add to `MartenCommitListener`
+- ❌ Missing SSE notification → Add handler in `ProjectionCommitListener`
 - ❌ Missing cache invalidation → Call `RemoveByTagAsync` after mutations
 - ❌ Manually running Marten async daemon → Async projections are updated by Wolverine
 - ❌ Skipping tenant context → Use tenant-scoped sessions and cache keys
 - ❌ Ignoring ETag checks → Use `IHaveETag` and `ETagHelper`
 - ❌ Returning plain JSON errors → ALL failures must return ProblemDetails with error codes (endpoints, handlers, middleware)
+- ❌ `DateTimeOffset` precision in aggregates → URL params lose sub-second precision; compare stored values with `TruncateToSeconds` in `Apply()` methods, and store the canonical `sale.Start` from aggregate state (not the incoming URL parameter) in events
 
 ## Project Layout
 | Path | Purpose |

src/BookStore.ApiService/Aggregates/BookAggregate.cs

@@ -77,7 +77,7 @@ void Apply(BookSaleScheduled @event)
         Sales.Add(@event.Sale);
     }
 
-    void Apply(BookSaleCancelled @event) => _ = Sales.RemoveAll(s => s.Start == @event.SaleStart);
+    void Apply(BookSaleCancelled @event) => _ = Sales.RemoveAll(s => TruncateToSeconds(s.Start) == TruncateToSeconds(@event.SaleStart));
 
     void Apply(BookDiscountUpdated @event) => CurrentDiscountPercentage = @event.DiscountPercentage;
 
@@ -399,13 +399,13 @@ public Result<BookSaleCancelled> CancelSale(DateTimeOffset saleStart)
             return Result.Failure<BookSaleCancelled>(Error.Conflict(ErrorCodes.Books.AlreadyDeleted, "Cannot cancel sale for a deleted book"));
         }
 
-        var sale = Sales.FirstOrDefault(s => s.Start == saleStart);
+        var sale = Sales.FirstOrDefault(s => TruncateToSeconds(s.Start) == TruncateToSeconds(saleStart));
         if (sale.Equals(default(BookSale)))
         {
             return Result.Failure<BookSaleCancelled>(Error.NotFound(ErrorCodes.Books.SaleNotFound, "No sale found with the specified start time"));
         }
 
-        return new BookSaleCancelled(Id, saleStart);
+        return new BookSaleCancelled(Id, sale.Start);
     }
 
     public Result<BookDiscountUpdated> ApplyDiscount(decimal percentage)
@@ -432,5 +432,8 @@ public Result<BookDiscountUpdated> RemoveDiscount()
 
         return new BookDiscountUpdated(Id, 0);
     }
+
+    static DateTimeOffset TruncateToSeconds(DateTimeOffset dt)
+        => new(dt.Year, dt.Month, dt.Day, dt.Hour, dt.Minute, dt.Second, dt.Offset);
 }
 

src/BookStore.ApiService/Aggregates/SaleAggregate.cs

@@ -18,7 +18,8 @@ internal void Apply(BookSaleScheduled @event)
         ScheduledSales.Add(@event.Sale);
     }
 
-    internal void Apply(BookSaleCancelled @event) => _ = ScheduledSales.RemoveAll(s => s.Start == @event.SaleStart);
+    internal void Apply(BookSaleCancelled @event)
+        => _ = ScheduledSales.RemoveAll(s => TruncateToSeconds(s.Start) == TruncateToSeconds(@event.SaleStart));
 
     public Result<BookSaleScheduled> ScheduleSale(decimal percentage, DateTimeOffset start, DateTimeOffset end)
     {
@@ -44,12 +45,17 @@ public Result<BookSaleScheduled> ScheduleSale(decimal percentage, DateTimeOffset
 
     public Result<BookSaleCancelled> CancelSale(DateTimeOffset saleStart)
     {
-        var sale = ScheduledSales.FirstOrDefault(s => s.Start == saleStart);
+        // Truncate to seconds to be resilient against sub-second precision loss during URL serialization
+        var normalizedStart = TruncateToSeconds(saleStart);
+        var sale = ScheduledSales.FirstOrDefault(s => TruncateToSeconds(s.Start) == normalizedStart);
         if (sale.Equals(default(BookSale)))
         {
             return Result.Failure<BookSaleCancelled>(Error.NotFound(ErrorCodes.Books.SaleNotFound, "No sale found with the specified start time"));
         }
 
-        return new BookSaleCancelled(Id, saleStart);
+        return new BookSaleCancelled(Id, sale.Start);
     }
+
+    static DateTimeOffset TruncateToSeconds(DateTimeOffset dt)
+        => new(dt.Year, dt.Month, dt.Day, dt.Hour, dt.Minute, dt.Second, dt.Offset);
 }

src/BookStore.ApiService/Endpoints/SalesEndpoints.cs

@@ -0,0 +1,59 @@
+using BookStore.ApiService.Infrastructure;
+using BookStore.ApiService.Projections;
+using BookStore.Shared.Models;
+using Marten;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Options;
+
+namespace BookStore.ApiService.Endpoints;
+
+public static class SalesEndpoints
+{
+    public static RouteGroupBuilder MapSalesEndpoints(this RouteGroupBuilder group)
+    {
+        _ = group.MapGet("/", GetSales)
+            .WithName("GetSales")
+            .WithSummary("Get all scheduled book sales");
+
+        return group.RequireAuthorization("Admin");
+    }
+
+    static async Task<IResult> GetSales(
+        [FromServices] IQuerySession session,
+        [FromServices] IOptions<PaginationOptions> paginationOptions,
+        [AsParameters] PagedRequest request,
+        CancellationToken cancellationToken)
+    {
+        var paging = request.Normalize(paginationOptions.Value);
+        var now = DateTimeOffset.UtcNow;
+
+        var books = await session.Query<BookSearchProjection>()
+            .Where(b => !b.Deleted)
+            .ToListAsync(cancellationToken);
+
+        var allSales = books
+            .Where(b => b.Sales.Count > 0)
+            .SelectMany(b => b.Sales.Select(sale => new SaleDto
+            {
+                Id = b.Id,
+                BookTitle = b.Title,
+                BuyerName = string.Empty,
+                Date = sale.Start,
+                EndDate = sale.End,
+                Amount = sale.Percentage,
+                Status = now >= sale.Start && now < sale.End ? "Active"
+                       : now < sale.Start ? "Upcoming"
+                       : "Expired",
+                ETag = ETagHelper.GenerateETag(b.Version)
+            }))
+            .OrderByDescending(s => s.Date)
+            .ToList();
+
+        var totalCount = allSales.Count;
+        var page = paging.Page!.Value;
+        var pageSize = paging.PageSize!.Value;
+        var items = allSales.Skip((page - 1) * pageSize).Take(pageSize).ToList();
+
+        return Results.Ok(new PagedListDto<SaleDto>(items, page, pageSize, totalCount));
+    }
+}

src/BookStore.ApiService/Infrastructure/Extensions/EndpointMappingExtensions.cs

@@ -65,6 +65,10 @@ static void MapPublicEndpoints(WebApplication app, Asp.Versioning.Builder.ApiVer
             .MapNotificationEndpoints()
             .WithTags("Notifications");
 
+        _ = publicApi.MapGroup("/sales")
+            .MapSalesEndpoints()
+            .WithTags("Sales");
+
         // Shopping Cart endpoints
         app.MapShoppingCartEndpoints();
     }

src/BookStore.Client/BookStoreClientExtensions.cs

@@ -1,3 +1,5 @@
+using System.Globalization;
+using System.Reflection;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 using Refit;
@@ -9,6 +11,11 @@ namespace BookStore.Client;
 /// </summary>
 public static class BookStoreClientExtensions
 {
+    // Use ISO 8601 round-trip format for DateTimeOffset query params to preserve sub-second precision
+    static readonly RefitSettings DefaultSettings = new()
+    {
+        UrlParameterFormatter = new Iso8601DateTimeOffsetFormatter()
+    };
     /// <summary>
     /// Registers all BookStore API client interfaces with the service collection.
     /// </summary>
@@ -45,7 +52,7 @@ public static IServiceCollection AddBookStoreClient(
     // Helper to register client with standard configuration
     static IHttpClientBuilder AddClient<T>(this IServiceCollection services, Uri baseAddress, Action<IHttpClientBuilder>? configureClient = null) where T : class
     {
-        var builder = services.AddRefitClient<T>()
+        var builder = services.AddRefitClient<T>(DefaultSettings)
             .ConfigureHttpClient(c => c.BaseAddress = baseAddress)
             .AddHttpMessageHandler<BookStore.Client.Infrastructure.BookStoreHeaderHandler>()
             .AddHttpMessageHandler<BookStore.Client.Infrastructure.BookStoreErrorHandler>();
@@ -91,3 +98,15 @@ public static IServiceCollection AddBookStoreEvents(
         return services;
     }
 }
+
+/// <summary>
+/// Formats <see cref="DateTimeOffset"/> query parameters using the ISO 8601 round-trip format ("O")
+/// to preserve sub-second precision through URL serialization.
+/// </summary>
+sealed class Iso8601DateTimeOffsetFormatter : DefaultUrlParameterFormatter
+{
+    public override string? Format(object? parameterValue, ICustomAttributeProvider attributeProvider, Type type)
+        => parameterValue is DateTimeOffset dto
+            ? dto.ToString("O", CultureInfo.InvariantCulture)
+            : base.Format(parameterValue, attributeProvider, type);
+}

src/BookStore.Shared/SaleDto.cs

@@ -6,6 +6,8 @@ public record SaleDto
     public string BookTitle { get; init; } = string.Empty;
     public string BuyerName { get; init; } = string.Empty;
     public DateTimeOffset Date { get; init; }
+    public DateTimeOffset EndDate { get; init; }
     public decimal Amount { get; init; }
     public string Status { get; init; } = string.Empty;
+    public string? ETag { get; init; }
 }

src/BookStore.Web/AGENTS.md

@@ -10,13 +10,19 @@
 ✅ Use BookStore.Client Refit clients  ❌ Call API endpoints directly
 ✅ ReactiveQuery<T> for reads          ❌ Manual data fetch without invalidation
 ✅ QueryInvalidationService + SSE      ❌ Polling for updates
-✅ OptimisticUpdateService for writes  ❌ UI waits for server roundtrip
+✅ MudTable Items=@(_query?.Data)      ❌ MudTable ServerData= on SSE-driven pages
+✅ _query?.MutateData for instant UI   ❌ await API then reload (blocks UX)
+✅ _query.InvalidateAsync() after dialogs ❌ _table.ReloadServerData() after mutations
 ✅ TenantService for tenant context    ❌ Hardcoded tenant or missing headers
 ```
 
 ## Common Mistakes
 - ❌ Calling HttpClient directly → Use injected BookStore.Client interfaces
-- ❌ Missing SSE invalidation mapping → Update QueryInvalidationService rules
+- ❌ `MudTable ServerData=` on SSE-driven admin pages → SSE-triggered reloads bypass `ServerData`; use `ReactiveQuery<IReadOnlyList<T>>` + `Items=@(_query?.Data)` instead
+- ❌ Missing SSE invalidation mapping → Update `QueryInvalidationService`; if the entity is stored inside a parent projection (e.g., sales inside `BookSearchProjection`), the parent notification must also yield the child query key
+- ❌ Forgetting rollback on failed mutations → Take a snapshot before `MutateData`, restore it in the catch block
+- ❌ Using `MutateData` for dialog-based mutations → Only use `MutateData` for inline single-step operations (cancel, delete); after dialogs use `_query.InvalidateAsync()` so the server response is the source of truth
+- ❌ Optimistic removal that leaves stale items after SSE → `MutateData` removes the row immediately; SSE then triggers a silent background `InvalidateAsync()` via `ReactiveQuery`, which replaces the local state; no extra reload needed
 - ❌ Business logic in .razor files → Move to Services/ or backing classes
 - ❌ Tenant mismatch in UI → Use TenantService and tenant-aware clients